Row-Bot

July 18, 2026 · View on GitHub

Full technical reference for every feature, module, and subsystem in Row-Bot. For a concise overview, see the README.

Row-Bot is the renamed successor to Thoth. The product name is also the design principle for the system: Reason. Orchestrate. Work. The architecture keeps those concerns separate: reasoning lives in provider-aware agent/runtime paths, orchestration lives in tools, workflows, channels, skills, plugins, and MCP, and durable work lives in local data stores owned by the user.

Table of Contents

ReAct Agent Architecture

  • Autonomous tool use — the agent decides which tools to call, when, and how many times, based on your question
  • 30+ core tools plus Agent, Goal, Developer, Custom Tool, Skills Hub, and auto-generated channel tools — web search, email, calendar, file management, shell access, browser automation, opt-in native Computer Use, vision, image generation, video generation, X (Twitter), a personal knowledge graph, Agent Profiles, Goal Mode, child-agent delegation, Designer Studio, Developer Studio, Custom Tool Builder, scheduled workflows, habit tracking, Row-Bot Status self-inspection, external MCP tools, and more
  • Streaming responses — tokens stream in real-time with a typing indicator
  • Thinking indicators — shows when the model is reasoning before responding
  • Smart context management — automatic conversation summarization compresses older turns when token usage exceeds 80% of the context window, preserving the 5 most recent turns and a running summary; a hard trim at 85% drops oldest messages as a safety net; oversized tool outputs are proportionally shrunk so multi-tool chains fit within context; accurate token counting via tiktoken (cl100k_base)
  • Dynamic tool budgets — the agent automatically adjusts how many tools are exposed to the model based on available context headroom; when context usage is high, lower-priority tools are temporarily hidden to prevent the system prompt from crowding out conversation history
  • Explicit prompt context/cache sections — prompt_context.py assembles named stable and ephemeral sections so identity, profile, platform, self-knowledge, tool guides, manual skills, plugin skills, turn state, memory recall, Developer context, Designer context, channel state, and history have deterministic cache behavior
  • Runtime readiness routing — before building the graph, selected models are evaluated for context headroom, provider capability metadata, tool support, and surface requirements; full agent mode, chat-only mode, and blocked states are explicit outcomes rather than accidental provider failures
  • Chat-only runtime — models that are useful for normal conversation but cannot reliably accept tool schemas use a compact tool-free prompt, a shaped transcript without full tool bodies, and the normal streaming/persistence path
  • Profile- and skill-aware prompting — Agent Profiles, manual Smart Skills, per-thread/per-workflow skill overrides, and tool guides are resolved before prompt assembly so the agent receives only the relevant operating instructions for the current surface
  • Scoped delegation — parent agents can delegate focused work to durable child-agent runs with profile snapshots, context summaries, tool allowlists, wait/stop/status controls, and parent-thread event history instead of hiding long-running subtasks inside one opaque turn
  • Provider transcript normalization — model-facing histories are checked for duplicate tool-call IDs, orphan tool results, invalid tool calls, empty assistant turns, and unsafe reasoning/tool artifacts before replay to custom or hosted providers
  • Centralized prompts plus self-knowledge injection — base prompt templates live in prompts.py, while self_knowledge.py injects a dynamic identity line, capability manifest, and live runtime state so Row-Bot can describe itself accurately without stale hard-coded copy
  • Live token counter — progress bar in the sidebar shows real-time context window usage based on trimmed (model-visible) history
  • Generation-scoped stop & error recovery — each active generation owns a cancellation scope that closes registered provider responses, terminates registered subprocesses, wakes queued state, and stops only generation-linked child runs; checkpointed model-iteration budgets and no-progress detection wind down long or repetitive tool loops; orphaned tool calls are repaired; provider/API errors are surfaced as persistent red toasts and saved to the conversation checkpoint so they survive thread refresh
  • Workflow cancellation — running background workflows can be stopped from the chat header, activity panel, or workflow card; cancellation is checked between every LangGraph node for clean shutdown
  • Displaced tool-call auto-repair — if context trimming displaces tool-call/response pairs, the agent automatically detects and repairs the ordering before the next LLM call; orphaned tool calls trigger an automatic retry
  • Grouped tool traces — repeated tool calls of the same type are grouped into expandable transcript entries, keeping long research, browser, and Developer runs readable while preserving individual results
  • Thinking retention — non-empty reasoning/thinking text is preserved across streaming, detached reattach, checkpoint loading, and final transcript rendering without treating reasoning-only chunks as user-visible final answers
  • Date/time awareness — current date and time is injected into every LLM call so the model always knows "today"
  • Destructive action confirmation — dangerous operations (file deletion, sending emails, deleting calendar events, deleting memories, deleting workflows, selected settings changes) require explicit user approval via an interrupt mechanism
  • Workflow-scoped background permissions — background workflows use a tiered system: safe operations always run, low-risk operations (move file, move calendar, send email) are allowed with optional runtime guards, and irreversible operations (delete file, delete memory) are always blocked; shell commands and email recipients can be allowlisted per-workflow via the editor UI

Generation Cancellation & Stop Propagation

Stop is modeled as generation-scoped control state rather than a UI-only event. cancellation.py binds one CancellationScope to an active generation and lets provider transports, subprocesses, tools, and child-agent scheduling register cleanup callbacks against that scope. This keeps cancellation local to the turn the user stopped while allowing blocked I/O to be interrupted immediately.

  • Scope lifecycle — request_generation_stop() marks the active generation stopped, sets its stop event, cancels its scope, detaches or wakes queued UI state, and leaves unrelated generations and child runs untouched
  • Provider response closure — providers/transports/cancellable_http.py, anthropic_cancellable.py, and openrouter_cancellable.py register in-flight sync/async responses for closure across direct OpenAI, Anthropic, xAI, MiniMax, OpenRouter, OpenCode, and compatible runtime construction paths
  • Custom transport propagation — Codex, Claude Subscription, Ollama Cloud, xAI OAuth Responses, and shared OpenAI-compatible transports register their request/stream handles with the same scope
  • Cancellable subprocesses — process_cancellation.py starts process groups, captures output, enforces timeouts, and terminates the group when the generation scope is cancelled; shell and Developer commands return an explicit stopped result instead of remaining blocked
  • Tool integration — browser and Computer Use actions, MCP probes/tool calls, shell sessions, Developer runtime processes, and voice-agent turns check or register with the current scope at their blocking boundaries
  • Child-run ownership — generation-linked async child runs are tracked separately from older or independently started child work, so Stop terminates only the runs created for that generation
  • Cancellation-safe finalization — UI and channel delivery paths distinguish cancellation from successful final output, clean partial previews, avoid false completion persistence, and retain durable state needed for a later user turn
  • Deterministic coverage — focused tests close fake HTTP responses, terminate fake subprocess groups, cancel provider and tool waits, wake generation queues, and prove unrelated child runs survive

Agent Execution Budgets & Delegation Capacity

Agent limits are explicit application state rather than hidden framework recursion constants. agent_budget.py owns one checkpoint-safe budget per logical turn, while agent_settings.py owns the application-wide defaults used by new parent and child runs.

  • Narrow checkpoint schema — each turn stores a schema version, opaque budget id, logical turn id, maximum and used model iterations, finalization flags, and terminal reason without persisting tool arguments or model input
  • Provider-response charging — a pre-model hook verifies remaining capacity immediately before a provider call, and a post-model hook charges exactly one iteration only after a successful provider response
  • Derived graph ceiling — the LangGraph recursion limit is calculated from remaining model iterations, keeping the framework guard above the authoritative product budget instead of using it as the user-visible limit
  • Interrupt and resume continuity — approvals and other checkpoint interrupts keep the same budget identity and used count; legacy interrupted checkpoints without a budget receive one bounded migration value before resuming
  • Exactly-once terminal response — budget exhaustion claims one tool-free finalization pass, persists its started/completed state, and prevents duplicate finals when UI, child-run, or resume paths observe the same terminal condition
  • No-progress detection — exact tool name/argument requests are represented only by a process-keyed HMAC digest; the fourth identical request is blocked and a continued fifth request terminates the turn as no_progress
  • Durable progress — successful model rounds update agent_runs.model_iterations_used, the snapshotted maximum, and heartbeat/active-time metadata without copying model inputs into the Agent Run database
  • Typed runtime settings — agent_settings.json stores maximum work rounds, nested child levels, active children per parent, active children across the application, and optional child active-time seconds through validated atomic writes
  • Reviewed defaults — new runs default to 90 model iterations, one child level, three active children per parent, eight active children globally, and no child timeout
  • FIFO capacity queue — agent_runner.py admits a child only when both parent and global capacity are available; excess children remain queued in order and can still be stopped while waiting
  • Snapshot semantics — each Agent Run stores the effective settings snapshot it started with, so later Settings changes affect only new runs and cannot alter an interrupted or active run mid-flight
  • Active-time timeout — the optional child timer starts only after capacity and any write lock are acquired, excludes queue time, and records timeout as a durable terminal reason

Agent Profiles, Goal Mode & Child Agents

Agent Profiles and Goal Mode sit above the base ReAct loop. They let a normal conversation become a visible, role-aware work session without turning Row-Bot into an unbounded autonomous system.

Agent Profiles

  • Profile model — agent_profiles.py stores built-in and user profiles with slug, display name, description, when-to-use guidance, instructions, handoff contract, enabled state, and JSON policy blocks for tools, skills, context, workspace, and approvals
  • Profile snapshots — each run receives a profile snapshot so long-running child agents keep the instructions and policy they started with even if the profile library changes later
  • Prompt integration — agent.py injects the active profile as a structured system context for normal agent runs and chat-only turns; missing or disabled profiles produce a model-visible warning and user-facing recovery guidance instead of failing silently
  • Thread binding — threads.py stores the selected profile for a thread, while profile_library.py, profile_picker.py, and slash/profile commands expose selection and review without requiring manual config edits
  • Policy summary — profile prompt context includes capability, context, workspace, allowed tools, and pinned profile skills so the model sees a compact boundary rather than the entire profile JSON
  • Built-in profiles — the bundled profile library provides focused roles for research, review, implementation, orchestration, and other repeatable work patterns; users can duplicate or save profiles when a successful run should become reusable guidance

Goal Mode

  • Durable goal state — goals.py persists the current thread goal with objective, status, progress, evidence, blockers, next step, turn count, max turns, active run id, and completion/block verdict metadata
  • Goal tools — tools/goal_tool.py registers goal_update and goal_status so agents can report progress, evidence, blockers, or completion through structured state instead of relying only on prose in the transcript
  • Visible progress — ui/goal_ui.py, the Command Center, and streaming/status surfaces show active goal state, grouped goal activity, and blockers while the user continues working elsewhere
  • Channel support — channel command/runtime paths carry goal context so work started from Telegram, WhatsApp, Discord, Slack, or SMS can still update the same durable thread goal
  • Bounded persistence — goals are local records, not hidden background mandates; users can clear or replace them, and goal completion is based on evidence plus explicit agent status rather than unchecked self-assertion

Child-Agent Runs

  • Durable run store — agent_runs.py stores child-agent runs with parent thread id, parent run/message ids, objective, display name, profile id/snapshot, context summary, enabled tools, model override, skills/tools overrides, approval mode, status, status message, summary, and event history
  • Runner lifecycle — agent_runner.py queues, starts, waits for, stops, and finalizes child runs while preserving terminal states and recent events for parent inspection
  • Capacity and timeout policy — child runs queue against snapshotted per-parent/global concurrency limits, enforce configured nesting depth, and can use an opt-in active-execution timeout that excludes queue time
  • Delegation tools — tools/agent_tool.py exposes delegate_work, agent_status, agent_wait, agent_stop, agent_profiles, agent_profile_save, agent_message, and agent_promote
  • Parent visibility — parent agents can inspect one run, list child runs for the current thread, wait for a result, or record a steering message for queued/non-terminal work without interrupting an active model call mid-token; durable lifecycle cards and completion summaries survive checkpoint reloads and queued parent turns
  • Parent-thread approvals — child-agent approval requests are serialized through approval_messages.py and agent_run_messages.py, appended once to the parent thread, and refreshed through run-state keys so background work cannot wait invisibly
  • Approval explanations — approval cards prefer a bounded, redacted model-supplied reason while preserving the raw command/action payload for the real safety decision; shell and Developer tools accept a dedicated approval_reason field
  • Terminal channel notices — async child completions can enqueue a compact once-only notice for the originating channel; failed delivery remains pending and is reconciled when channels auto-start again
  • Promotion paths — completed child runs can be promoted into a new Agent Profile or a disabled manual workflow; both paths are approval-gated and leave artifacts reviewable before reuse
  • Tool allowlists — profile and delegation tool allowlists flow into agent graph construction; plugin and MCP tools honor the allowlist so a child agent can run with a narrower tool surface than the parent
  • Write-lock safeguards — active-run queue and write-lock tests prevent child agents from silently colliding with parent or sibling work when a profile/workspace requires single-writer behavior
  • Status diagnostics — Row-Bot Status can report agent/profile/run state, making delegated work visible to diagnostics and support flows rather than trapping it in transient UI state
  • Budget diagnostics — run rows expose safe used/maximum model-iteration counts and terminal reasons, while active settings and dispatcher capacity remain queryable without exposing prompts or tool arguments

Long-Term Memory & Knowledge Graph

Row-Bot doesn't just store isolated facts — it builds a personal knowledge graph: a connected web of people, places, preferences, events, and their relationships. Every memory is an entity linked to others through typed relations, so the agent can reason about how things in your life connect.

  • Entity-relation model — memories are stored as entities with a type, subject, description, aliases, and tags; entities are connected by typed directional relations (e.g. Dad --[father_of]--> User, User --[lives_in]--> London)
  • 10 entity types — person, preference, fact, event, place, project, organisation, concept, skill, media
  • Memory tool — 7 sub-tools let the agent save, search, list, update, delete, link, and explore memories through natural conversation
  • Link memories — the agent can create relationships between any two entities, building a richer graph over time
  • Explore connections — the agent can traverse the graph outward from any entity, discovering chains of relationships for broad questions like family, work, and projects
  • Interactive memory visualization — a dedicated Knowledge surface renders the entire knowledge graph as an interactive network diagram with search, filters, full-graph / ego-graph toggle, and detail cards
  • Bounded auto-recall policy — before every response, memory_policy.py builds a deterministic recall query, retrieves candidates, scores them against tier/status/confidence/evidence/recency/query fit, applies a context-aware token budget, and records a compact recall trace for diagnostics
  • Hybrid recall candidates — recall combines FAISS semantic search, FTS5 lexical search, keyword fallback, and graph-neighbor expansion; strong seed memories can pull in related entities with relation confidence and hop metadata
  • Bounded semantic fallback — missing, failed, or slow local embedding loads set a structured fallback code and continue through lexical, keyword, and graph retrieval instead of blocking the turn or downloading a model implicitly
  • Single visible fallback notice — memory_policy.py deduplicates one display-safe notice per generation, explains the local model recovery action, and records timing/status metadata without including memory content
  • Recall-safe retrieval — candidate inspection does not mutate memory state; only memories actually injected into the turn are reinforced with recalled_at and recall-count metadata
  • Automatic memory extraction — a background process scans past conversations on startup and every 6 hours, extracting entities and relations the agent missed during live conversation; active threads and workflow threads are excluded; assistant messages are truncated to 200 chars to prevent extracting from AI-generated content; low-confidence relations are skipped and conflicting facts can be marked for review instead of overwriting high-authority user edits
  • Deterministic deduplication — both live saves and background extraction check for existing entities by normalized subject before creating new entries; cross-category matching prevents fragmentation; alias resolution ensures related names merge; richer content is always kept
  • Memory evolution metadata — memory_evolution.py normalizes status (active, needs_review, superseded, archived), tier (core, semantic, episodic, resource), confidence, evidence, source context, manual edits, superseding, archival, and journal entries
  • Vague-type banning — related_to, associated_with, connected_to, linked_to, has_relation, involves, and correlates_with are rejected before saving, preventing noisy low-value edges
  • Relation pre-normalization — alias forms are canonicalized before ban, confidence, and dedup checks
  • 67 valid relation types — curated vocabulary with 60+ alias mappings plus document-specific relations like extracted_from, uploaded, builds_on, cites, extends, and contradicts
  • Source and audit tracking — each entity is tagged with its origin (live, extraction, dream_*, document-derived, wiki-synced, or manual) plus audit metadata such as status, tier, confidence, evidence, source context, and user-modified timestamps
  • Semantic and lexical recall indexes — FAISS vectors are backed by the configured embedding provider, while an optional FTS5 entity index supports exact/keyword recall and fallback search
  • Memory IDs in context — auto-recalled memories include their IDs so the agent can update or delete specific entries when the user corrects previously saved information
  • Consolidation utilities — built-in duplicate consolidation merges near-duplicate memories that may accumulate over time
  • Local SQLite + NetworkX + FAISS storage — entities and relations live in ~/.row-bot/memory.db, mirrored in a NetworkX graph for traversal, with FAISS vectors in ~/.row-bot/memory_vectors/
  • Knowledge audit UI — browse, search, visualize, review, restore, supersede, archive, and bulk-delete memories from the Knowledge tab and entity editor, including graph statistics, audit badges, recall traces, and the memory evolution journal

Wiki Vault

The knowledge graph can be exported as a structured Obsidian-compatible markdown vault — one .md file per entity with YAML frontmatter, [[wiki-links]], and auto-generated indexes.

  • Vault structure — entities grouped by type (wiki/person/, wiki/project/, wiki/event/, etc.) with one .md file per entity; sparse entities (<20 chars) roll up into _index.md per type; per-type indexes and a master index.md are auto-generated on rebuild
  • YAML frontmatter — each article includes id, type, subject, aliases, tags, source, created, and updated metadata
  • Wiki-links — related entities linked via [[Entity Name]] syntax, enabling Obsidian backlinks and graph view
  • Connections section — outgoing and incoming relations listed with arrow notation
  • Live export — entities are exported on save, deleted on entity removal, and rebuilt on batch operations
  • Search — full-text search across all .md files with title, snippet, and entity ID results
  • Conversation export — any thread can be exported as a vault-compatible markdown file
  • Agent tools — wiki_read, wiki_rebuild, wiki_stats, and wiki_export_conversation let the agent interact with the vault directly
  • Settings UI — enable/disable toggle, vault path configuration, stats display, rebuild, and open-folder actions in the Knowledge tab

Dream Cycle

A 5-phase background daemon refines the knowledge graph during idle hours and ends with an insight-generation pass over recent system activity.

  • Phase 1: Duplicate merge — entities with ≥0.93 semantic similarity and same type are merged; the LLM synthesizes the best description, aliases are unioned, and relations are re-pointed to the survivor
  • Subject-name guard — entities with different normalized subjects require ≥0.98 similarity to merge, preventing false merges of distinct people or concepts
  • Phase 2: Description enrichment — thin entities (<80 chars) appearing in multiple conversations get richer descriptions from conversation context and graph neighborhood
  • Phase 3: Confidence decay — stale dream_infer relations older than 90 days lose 10% confidence per cycle; very low-confidence edges are pruned automatically
  • Phase 4: Relationship inference — co-occurring entity pairs with no meaningful edge are evaluated for a specific typed relation; hub diversity caps, batch rotation, half-overlap reuse, multi-excerpt evidence, and a 7-day rejection cache improve quality and reduce repetition
  • Phase 5: Insights analysis — the system captures a snapshot of recent logs, provider/model/media configuration, channels, task state, memory stats, skills, and existing insights, feeds it to DREAM_INSIGHTS_PROMPT, and stores actionable results in insights.py
  • Three-layer anti-contamination — sentence-level excerpt filtering, deterministic post-enrichment validation, and strengthened prompting prevent cross-entity fact bleed
  • Ollama busy check — queries /api/ps before starting; defers if Ollama is actively serving a user request to avoid competing for GPU or CPU
  • Configurable window — default 1–5 AM local time; checks every 30 minutes if enabled, idle, in window, and not yet run that day
  • Dream journal — all operations logged to ~/.row-bot/dream_journal.json with cycle ID, summary, duration, merges, enrichments, inferences, insights, and errors
  • Post-cycle rebuilds — FAISS is rebuilt after the cycle, and the wiki vault is regenerated when enabled so downstream views stay in sync
  • Manual trigger — a dedicated Dream button in the Knowledge surface can start the cycle immediately
  • Settings UI — enable/disable toggle, quiet window controls, and last-run summary in the Preferences tab

Document Knowledge Extraction

Uploaded documents are processed through a three-phase map-reduce LLM pipeline that extracts structured knowledge into the graph with full source provenance.

  • Map phase — each document is split into ~6K-char windows; each window is summarized to 3–5 sentences
  • Reduce phase — window summaries are combined into a coherent 300–600 word article
  • Extract phase — core entities and relations are pulled from the final article; extraction is capped at 12 entities per document to prevent over-extraction
  • Curated relation vocabulary — 67 valid relation types with 60+ alias mappings remove unknown-type churn and keep document-derived edges consistent with live memory extraction
  • Hub entity — the document itself is saved as a media entity; extracted entities link back via extracted_from for provenance tracking
  • Quality gates — minimum description length, self-loop rejection, and vague-relation bans keep output usable
  • Resource memory metadata — document hub entities and extracted facts are written with resource-tier provenance, confidence, evidence, and audit fields so document knowledge can be reviewed without overwriting personal memories blindly
  • Cross-window dedup — repeated entities across windows are merged before saving
  • Cross-source merge protection — document-derived content uses a stricter semantic merge threshold when it resembles a personal entity, reducing the chance of impersonal text overwriting personal knowledge
  • Supported formats — PDF, DOCX, TXT, Markdown, HTML, and EPUB
  • Live progress — the status bar shows an extraction pill with phase, progress, queue depth, and a stop action
  • Background queue — worker thread processes one document at a time
  • Per-document cleanup — removing a document deletes vector-store entries and extracted graph content associated with its source tag

Brain Model & Providers

The brain model is Row-Bot's default LLM — the model used for conversations, memory extraction, dream analysis, and any thread, profile, child-agent run, or workflow without a specific override. It is selected during setup or later from Settings, and can come from the supported local runtime, a hosted provider, Requesty, ChatGPT / Codex, Claude Subscription, xAI Grok OAuth, Ollama Cloud, or a custom OpenAI-compatible endpoint.

Row-Bot is local-first in its data model, but model routing is provider-neutral. Local models remain a first-class path for offline and private use, while hosted and self-hosted models can be selected per thread, workflow, Agent Profile, child-agent run, Developer workspace, or media surface. The setup wizard determines the initial default; on the local path, Row-Bot uses one of the models already exposed by the local runtime, with 14B-class models recommended for stronger agent/tool behavior.

Provider models are supported for users without a dedicated GPU, for frontier reasoning on demand, or for trying many providers without downloading large local weights. Row-Bot supports opt-in provider models through OpenAI (direct API), Anthropic (Claude through the API-key route), Google AI (Gemini), xAI (direct Grok API), xAI Grok OAuth (subscription/OAuth-backed Grok runtime and Grok Imagine media), MiniMax (live catalog through the Anthropic-compatible API), OpenCode providers, OpenRouter (many third-party models), Atlas Cloud (OpenAI-compatible access to Atlas-hosted chat, agent, and vision models discovered from the live provider catalog), Requesty (OpenAI-compatible model gateway with Requesty-specific catalog metadata), Ollama Cloud (direct API and local daemon cloud-tagged models), ChatGPT / Codex (subscription-backed Codex models), Claude Subscription (subscription-backed Claude models), and Custom/Self-hosted OpenAI-compatible endpoints such as oMLX, LM Studio, vLLM, llama.cpp, LocalAI, LiteLLM, SGLang, or private gateways. Provider connections, health, and credential sources are configured from Settings -> Providers; model catalog browsing, pinning, and defaults live in Settings -> Models.

The providers/ subsystem now owns provider config, auth metadata, model catalog normalization, capability resolution, runtime construction, display-safe status, runtime readiness, and Quick Choices. Model selections are preserved as provider-qualified refs (model:<provider>:<model>) at UI and settings boundaries so a local/custom model does not silently fall back to OpenRouter, xAI, or another provider when multiple providers expose the same or unknown bare model id. Existing public functions in models.py remain as compatibility facades while provider-backed selection is rolled through the app. Settings -> Models pickers are intentionally Quick Choice surfaces: catalog rows must be pinned before they become everyday Brain, Vision, Image, or Video choices, while the current default can still appear as a fallback value. providers/model_catalog_cache.py refreshes hosted-provider and local-runtime catalog rows in the background so Settings can render from cache without blocking on large remote catalogs. Targeted and scheduled refreshes iterate registered providers, including Codex subscription discovery, and commit rows provider-by-provider. Empty, failed, or partially paginated results retain that provider's last-known-good rows; successful results replace only that provider's rows. Provider Settings surfaces whether the current snapshot came from a live refresh, cache, or fallback.

Runtime readiness is evaluated before agent execution. providers/readiness.py, providers/resolution.py, and providers/capability_resolution.py resolve the selected model/provider, inspect cached capability snapshots, probe uncertain local/custom models when needed, compare the effective context window against tool-schema requirements, and return one of three outcomes: full agent mode, chat-only mode, or blocked with user-facing guidance. Forced-agent surfaces such as workflow execution, approval resumes, and Designer text generation request agent mode explicitly; normal chat can fall back to chat-only mode when a model is conversationally useful but not tool-compatible.

Provider-facing tool schemas are also checked at graph construction time. providers/tool_schema.py extracts each tool's effective JSON schema and applies a transport-scoped compatibility policy. For Google/Gemini, it validates both the source schema and the locked Google adapter's converted schema so every array has usable typed items. Optional incompatible tools are omitted in stable order; an explicitly selected incompatible tool produces a clear build error. Other transports retain the original tool objects unchanged. Built-in Gmail recipient arrays and Goal evidence/blocker arrays use concrete string item schemas while validators preserve compatible legacy input forms.

Atlas Cloud is a first-class provider with provider id atlascloud, not a generic custom endpoint profile. providers/atlascloud.py owns the Atlas setup copy, auth mapping to ATLASCLOUD_API_KEY, live catalog fetch, provider-qualified model refs, chat/agent/vision capability classification, and filtering rules. Atlas chat and multimodal rows can appear in Brain and Vision Quick Choices when their capability snapshot allows that surface, while Atlas image-generation and video-generation rows are intentionally filtered out of chat, agent, and vision pickers for this phase.

Atlas uses the shared OpenAI-compatible transport, but endpoint-specific behavior is scoped by provider id. The transport keeps Atlas tool-call buffering, Claude-shaped stream/error normalization, native tool-history replay cleanup, and Atlas-specific timeout/error text out of OpenRouter, custom endpoints, and other OpenAI-compatible providers unless those providers explicitly opt into the same path.

Requesty is a first-class OpenAI-compatible provider with provider id requesty. providers/requesty.py maps Requesty's live /models response into Row-Bot model metadata, including context_window, supports_tool_calling, supports_reasoning, supports_vision, task, modality, and nested capability fields. Requesty rows use provider-qualified refs and are filtered so embedding, image, video, audio, moderation, realtime, and other non-chat rows do not appear as Brain or agent choices.

xAI has two explicit provider paths. The existing xai provider uses XAI_API_KEY for direct API access. The new xai_oauth provider represents xAI Grok subscription/OAuth access, stores Row-Bot-owned OAuth tokens through the provider auth store, reports token health and OAuth client-id status, and uses provider-qualified refs so OAuth-backed Grok rows never collapse into API-key xAI rows.

providers/xai_oauth.py owns the OAuth PKCE flow, token refresh, account/user/email hash metadata, model catalog reads, runtime availability checks, runtime and vision probes, and display-safe status. providers/transports/xai_oauth_responses.py adapts the xAI Responses-style runtime into the same chat/model construction boundary as other first-class providers. providers/xai_catalog.py merges xAI /models and /language-models metadata for the API-key path, hides unusable rows, and preserves curated Grok chat and media entries when upstream catalogs omit expected rows.

Grok Imagine media is scoped through the provider/media layer instead of the chat model picker. providers/xai_media.py handles xAI image, video, and image-to-video request payloads, while providers/media.py, tools/image_gen_tool.py, and tools/video_gen_tool.py expose grok-imagine-image, grok-imagine-image-quality, and grok-imagine-video only on image/video surfaces when the relevant API-key or OAuth runtime is available.

ChatGPT / Codex is deliberately modeled as a subscription provider, not as another OpenAI API-key route. Direct Codex runtime requires Row-Bot's in-app ChatGPT device-flow sign-in so Row-Bot stores its own runnable OAuth tokens in the local OS credential store. Existing Codex CLI auth files can be referenced only as display-safe metadata: Row-Bot records that the external login exists, path/fingerprint metadata, and broad auth-file shape, but it does not copy runnable tokens from ~/.codex/auth.json.

Codex runtime uses ChatGPT's subscription/internal Codex backend rather than the public OpenAI API. That means endpoint behavior, catalog shape, auth requirements, rate limits, and model availability may change upstream. When a ChatGPT / Codex model is selected, the current conversation plus model-visible tool context and tool results are sent to ChatGPT / Codex for that turn. Durable Row-Bot data such as memories, documents, files, and other conversations remain local unless explicitly included in the active conversation or surfaced by a tool result.

Claude Subscription is also modeled as a subscription provider, not as another Anthropic API-key route. It uses provider id claude_subscription and requires provider-qualified refs such as model:claude_subscription:claude-sonnet-4-6; bare claude-* ids continue to infer the existing anthropic API provider for backward compatibility. Direct runtime requires Row-Bot-owned Claude OAuth tokens or an explicit user import into Row-Bot. External Claude Code files, CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN, and related Claude CLI state are discovery/import aids only and are not silently reused for runtime access.

Claude Subscription runtime uses Row-Bot's native Messages transport with OAuth bearer auth, streaming, image input, tool schemas, and tool-result replay through the normal Row-Bot agent loop. It never reads ANTHROPIC_API_KEY, never instantiates the Anthropic API-key runtime, and never falls back between the Anthropic API provider and the Claude Subscription provider. Row-Bot supports in-app Claude OAuth and explicit claude setup-token import as Row-Bot-owned auth paths; because public Claude subscription app access is still policy-sensitive upstream, this provider is treated as experimental and local-user-owned.

Claude Subscription's Settings card includes a runtime diagnostic that exercises native OAuth chat, a forced Row-Bot tool call, and tool-result replay. The diagnostic result is metadata-only state under providers.claude_subscription.last_runtime_probe; failed diagnostics downgrade only Claude Subscription readiness so an account/entitlement failure is visible without changing Anthropic API behavior. Claude Code claude -p remains part of the optional Claude Code Delegation workflow, not the Claude Subscription provider transport.

  • Dynamic model switching — change the brain model from Settings or approved row_bot_update_setting calls; choices are validated against pinned local/provider Quick Choices, installed local models, and provider catalogs before saving
  • Per-thread, per-profile, per-child-run & per-workflow model override — conversations, Agent Profiles, delegated child runs, and workflows can each run on a different model, with overrides persisted locally or snapshotted into the run
  • Quick Choices — models pinned from the consolidated Models catalog appear in chat, workflow, channel, Designer, status-tool, and Vision pickers when their capability snapshot supports that surface
  • Live provider discovery — provider catalogs can be refreshed from live APIs where supported; Atlas Cloud, MiniMax, Requesty, Codex, and other registered providers participate in targeted/scheduled refresh, xAI API-key rows merge the provider's available model endpoints, and Claude Subscription/xAI Grok OAuth use live catalog reads only with Row-Bot-owned OAuth so API-key and subscription model paths remain distinct
  • Provider-isolated catalog commits — refreshes preserve last-known-good rows for failed, empty, or partially paginated providers, replace only successfully refreshed provider rows, and record live/cached/fallback provenance for Settings and diagnostics
  • Gemini tool-schema compatibility — Google-bound tools are checked after adapter conversion for typed array items; optional incompatible tools are filtered, explicitly selected incompatible tools fail clearly, and non-Google transports remain unchanged
  • Prompt-cache gating — prompt_cache.py applies Anthropic cache_control markers only to eligible stable system content for the direct Anthropic API and normalizes provider cache read/write token metadata for diagnostics
  • Capability-aware surface filtering — catalog rows carry chat, agent/tool, vision, image, video, context, and provider provenance metadata; Brain, Vision, Image, and Video pickers each filter against the relevant surface instead of treating every remote catalog row as a runnable chat model
  • OpenCode provider runtime — OpenCode-compatible providers are represented as first-class provider/runtime entries with auth, catalog, selection, and readiness coverage instead of being treated as generic custom endpoints
  • Cost-efficient context management — smart context trimming compresses older conversation turns and shrinks oversized tool outputs, reducing token usage and API costs for provider models
  • Local catalog accuracy — installed Ollama chat models remain visible even when their family is newer than Row-Bot's curated tool/vision heuristics, while embedding-like local models are kept out of chat choices and Vision support is only inferred from known metadata/families
  • Ollama Cloud paths — direct Ollama Cloud API keys and local daemon :cloud models are represented separately while sharing catalog normalization and display metadata; direct API errors are normalized into user-facing provider messages
  • Tool-support validation — unsupported or uncertain local/custom models are warned about, can be probed with a real tool round-trip, and route to agent, chat-only, or blocked mode based on the result
  • Custom endpoint compatibility profiles — OpenAI-compatible endpoints can use oMLX, LM Studio, vLLM, llama.cpp, LocalAI, LiteLLM, SGLang, or generic profiles to normalize message content, tool history, unsupported parameters, streaming behavior, and request-time context settings
  • Custom endpoint probes — self-hosted/proxy endpoints can be probed for model catalog access, streaming deltas, tool-call round trips, native context metadata, and no-auth behavior; results are persisted with provider metadata for later routing decisions
  • Configurable context window — local and provider context caps can be set independently; actual model limits are still respected, override caches are invalidated when caps change, and custom endpoint profiles can pass capped context request parameters when the backend supports them
  • Provider transcript hygiene — provider-facing message histories are normalized to strip invalid tool calls, rewrite duplicate tool-call IDs, drop orphan tool results, flatten tool history for non-tool profiles, and preserve or suppress reasoning fields depending on endpoint support
  • Local & provider indicators — the UI clearly distinguishes downloaded local models, missing local models, and connected provider models
  • Provider vision detection — provider models with image capability are detected and reused by the Vision feature when available; Atlas-hosted multimodal chat models keep Vision capability when metadata or curated provider-family rules support it, and xAI Grok OAuth can run a vision probe to confirm Grok image-input support before advertising Vision readiness

Embeddings & Vector Indexing

Embeddings are configured separately from chat models so users can choose the privacy/performance tradeoff that fits document search, memory recall, and knowledge graph rebuilds.

  • embedding_config.py — persists the selected embedding provider, model, dimension metadata, and privacy-related settings
  • embedding_providers.py — normalizes local and cloud embedding backends behind one interface used by document search, memory recall, and graph/vector rebuilds
  • Local choices — Qwen3 0.6B, Nomic Embed Text v1.5, and Mixedbread Embed Large v1 are explicit local-cache choices; Mixedbread is the reviewed default
  • Cache-only normal runtime — local provider construction resolves a cached Hugging Face snapshot and passes local-only loading flags, so recall, indexing, status checks, startup, and normal background work cannot trigger a surprise download
  • Explicit download/repair — only the Settings download or repair action permits a remote snapshot fetch; status probes distinguish cached, missing, loading, failed, and ready states without starting a network call
  • Shared asynchronous load — concurrent recall callers share one background provider build; the first caller receives one bounded grace wait, later callers reuse the same state, and a completed load becomes available without rebuilding
  • Failure cache and fallback contract — missing, failed, and timeout conditions raise structured LocalEmbeddingUnavailable codes, fail fast on later callers, and let memory/document/workflow retrieval continue through bounded non-semantic paths
  • Cloud option — cloud embeddings can be enabled explicitly in Settings and show privacy copy because document or memory text is sent to the chosen embedding provider
  • Stale-index detection — vector stores record embedding provider and dimension metadata so Row-Bot can detect when a document or memory index was built with a different embedding configuration
  • Memory release — heavy document and extraction jobs release cached embedding resources after use to reduce long-session RSS growth
  • Settings integration — embedding provider controls live in the model/settings surfaces without overloading the chat model picker

Voice Input & Text-to-Speech

Row-Bot has two voice paths: a local STT/TTS loop for privacy-first dictation and playback, and a realtime voice runtime for lower-latency conversational sessions with provider-backed events and action handling.

  • Toggle-based voice — simple manual toggle to start and stop listening, no wake word required
  • Classic local pipeline — stopped -> listening -> transcribing -> muted state transitions keep manual speech input explicit and gate the microphone during playback
  • Local speech-to-text — transcription via faster-whisper (tiny/base/small/medium), CPU-only int8 quantization, no cloud APIs required
  • Neural TTS — high-quality text-to-speech via Kokoro, fully offline
  • 10 voice options — US and British English, male and female variants
  • Streaming TTS — responses are spoken sentence-by-sentence as they stream in
  • Mic gating — microphone is automatically muted during TTS playback to prevent echo and feedback loops
  • Realtime voice runtime — voice/realtime_client.py, voice/runtime.py, provider adapters, and UI event presenters coordinate low-latency sessions separately from the classic text-turn pipeline
  • Provider abstraction — realtime voice providers share a base contract for session setup, input/output events, speech status, and shutdown; OpenAI realtime and local-provider scaffolding are represented through the same runtime boundary
  • Agent bridge — voice/agent_bridge.py maps realtime voice events into Row-Bot agent actions without letting the voice client bypass tool, approval, or runtime readiness policy
  • Voice actions — voice/actions.py keeps action dispatch explicit so voice sessions can request supported app actions through controlled handlers
  • Cue and speech policy — voice/cue_policy.py, voice/cues.py, voice/speech_policy.py, and voice/output_controller.py coordinate conversational cues, spoken output timing, interruption, and playback state
  • UI lifecycle — ui/voice_lifecycle.py and ui/voice_realtime_events.py surface session state, provider events, and recovery paths without coupling the chat transcript directly to provider-specific event streams

Shell Access

  • Full shell access — the agent can run shell commands on your machine through natural conversation
  • Persistent sessions — cd, environment variables, and other shell state persist across commands within a conversation; each thread gets its own isolated shell session
  • 3-tier safety classification — commands are classified as safe, moderate, or blocked before execution
  • Safe commands run instantly — read-only operations like ls, pwd, cat, git status, or pip list execute without interruption
  • Dangerous commands require approval — destructive or system-modifying commands trigger an interrupt so you can accept or reject them
  • Blocked by default — high-risk commands like shutdown, reboot, or mkfs are rejected outright
  • Background safety integration — safe commands always execute; moderate commands are blocked by default in workflows but can be allowlisted per workflow; dangerous commands remain blocked
  • Inline terminal panel — command output appears in a collapsible terminal panel in the chat UI with clear and history controls
  • History persistence — shell history is saved per thread in ~/.row-bot/shell_history.json
  • Stop propagation — shell execution uses process_cancellation.py, so cancelling the owning generation terminates the command process group and returns a stopped result without losing persistent-session bookkeeping

Browser Automation

  • Full browser automation — the agent can navigate websites, click elements, fill forms, scroll pages, and manage tabs in a real, visible Chromium window
  • Shared visible browser — runs with headless=False so you can see what the agent is doing and intervene when needed
  • Persistent profile — cookies, logins, and local storage survive across restarts in ~/.row-bot/browser_profile/
  • Accessibility-tree snapshots — after every action the tool captures the page's accessibility tree with numbered references so the model can click and type by number
  • Smart snapshot filtering — deduplicates links, drops hidden elements, and caps interactive elements to keep context under control
  • Snapshot compression — older browser snapshots are compressed to short stubs while the latest state remains detailed
  • 7 browser operations — navigate, click, type, scroll, snapshot, back, and tab management
  • Per-thread tab isolation — each chat thread or background workflow gets its own browser tab; tabs are cleaned up on thread deletion or workflow completion
  • Navigation policy — destinations are normalized and checked before navigation, keeping blocked schemes and out-of-scope redirects from silently broadening the browser task
  • Consequence policy — browser mutations share approval/consequence classification with other action tools, while observations and reversible navigation remain distinct
  • Redacted durable history — typed values and sensitive action payloads are omitted from browser history and tool-trace persistence; the active accessibility snapshot remains model context rather than an audit copy of secrets
  • Live takeover state — browser tasks use the shared live-control view model for Stop, user takeover, and resume/done state without merging the browser DOM engine with native Computer Use
  • Automatic browser detection — prefers installed Chrome, then Edge on Windows, then Playwright's bundled Chromium
  • Crash recovery — if the browser closes externally, the next action relaunches it cleanly
  • Generation cancellation — browser operations check the active cancellation scope before and during blocking work so Stop can abandon the current action without affecting tabs owned by other threads

Native Computer Use (Beta)

Computer Use is a separate native-desktop engine for Windows and macOS. It does not reuse the browser's persistent profile or DOM references, and it does not turn the reviewed Cua Driver into a general MCP server. The accepted dependency and telemetry decision is documented in COMPUTER_USE_SECURITY.md.

  • Provider-neutral tool boundary — tools/computer_use_tool.py exposes launch, target-window observation, click, double-click, right-click, type, key/hotkey, scroll, and drag operations independently of the selected chat/agent provider
  • Private Cua client — computer_use/client.py starts the reviewed Cua Driver over a private stdio MCP transport, allows only the required tool names, normalizes results, disables upstream update checks, and never registers the process in the external MCP catalog
  • Pinned runtime manifest — computer_use/cua_runtime_manifest.json records Cua Driver Rust 0.7.1, upstream tag/commit, platform asset URLs, executable candidates, telemetry contract, and SHA-256 values for Windows x86-64, Windows ARM64, and macOS universal
  • Explicit verified install — computer_use/readiness.py downloads only after a user Install/Repair action, verifies the selected asset before safe extraction, writes a private runtime manifest under runtimes/cua-driver/, and never invokes Cua's installer or updater
  • Mandatory disclosure gate — every executable resolution/start path requires the current Cua telemetry notice version in computer_use_settings.json; Cancel removes acknowledgement and disables the native tool
  • Third-party telemetry boundary — the reviewed Cua telemetry includes a pseudonymous Cua installation id, Cua/OS/architecture metadata, event category, CI flag, and timestamp sent to Cua/PostHog. Row-Bot adds no first-party telemetry and keeps prompts, memories, secrets, screenshots, file paths, tool arguments, typed content, and channel data outside that telemetry
  • Exclusive task lease — computer_use/service.py gives one interactive local task ownership of discovery, target capture, Vision fallback, and input; schedules, channels, background workflows, child agents, headless/server callers, and plugin/general MCP callers cannot acquire it
  • Target-window capture — the session forces window-only capture and a bounded image dimension; desktop-wide capture, recording, browser/CDP, autostart, process-kill, update, maintenance, telemetry mutation, and arbitrary config surfaces remain blocked
  • Generation-bound references — application/window targets and accessibility elements are opaque, observation-generation-bound tokens invalidated by mutation, reconnect, target drift, approval waits, Stop, and takeover
  • Mutation-observation loop — every input action requires current scope, policy, target, and element validation and is followed by a fresh target-window observation before the agent can act again
  • Point-of-risk policy — computer_use/policy.py classifies routine, consequential, always-confirm, handoff, and blocked actions. Credentials, OTPs, CAPTCHAs, biometrics, UAC/TCC, terminals, password managers, Row-Bot itself, secure desktops, and elevation cannot be automated
  • Ephemeral privacy — screenshot bytes are not written to media or checkpoints; typed values are excluded from logs, histories, tool traces, approval payloads, memory, and durable state
  • Vision fallback — accessibility information remains primary. When it is insufficient, only the current target-window screenshot can be sent to the configured Vision provider, whose local/cloud disclosure is shown before setup
  • Live control UI — ui/live_control.py and ui/computer_use.py show sanitized app/state/thumbnail data plus direct Stop, Take over, and Resume actions. Take over cancels queued mutation, pauses the lease, and requires a fresh observation before resume
  • Readiness and recovery — Settings normalizes disabled, disclosure, unsupported, not-installed, hash/version mismatch, permission, degraded, ready, and failed states; macOS recovery links directly to Accessibility and Screen Recording panes and supports recheck after TCC changes
  • Lifecycle cleanup — generation Stop, thread cleanup, tool disablement, uninstall, and application shutdown stop the private client, invalidate targets, cancel queued work, and release the lease

Google Calendar

The Calendar tool keeps Google OAuth and operation policy in Row-Bot while treating Google client objects as request-scoped resources. This avoids sharing non-thread-safe discovery clients when an agent or ToolNode fans out operations within one turn.

  • Request-scoped services — every search, create, update, move, delete, or bulk-create invocation constructs an independent Calendar service from the current credential snapshot
  • Single-flight token refresh — concurrent callers coordinate one OAuth refresh and persist the refreshed token atomically before building their request-scoped services
  • Mutation serialization — writes are ordered inside the process so same-turn fan-out cannot race duplicate checks or issue overlapping mutations through shared state
  • Native bulk create — create_calendar_events accepts ordered event inputs, performs duplicate-safe creation, preserves result order, and returns structured success or partial-failure records
  • Ambiguous timeout reconciliation — create operations derive a stable correlation marker and search for a backend-committed event after a timeout before deciding whether to retry, preventing duplicate calendar entries
  • Bounded retries — transient SSL and Google backend failures retry with fresh service instances; permanent errors are returned once in structured form
  • Typed operation contracts — schemas cover calendar selection, timezones, attendees, conference data, notification behavior, update/move/delete fields, and destructive-operation classification
  • Concurrent regression coverage — deterministic tests exercise parallel reads, eight-way create fan-out, token refresh, transient retries, committed-timeout reconciliation, request scoping, and ordered bulk partial failure

Vision

  • Camera analysis — capture and analyze images from your webcam in real-time
  • Screen capture — take screenshots and ask questions about what is on your screen
  • Image file analysis — analyze workspace image files by path without needing a camera or live capture
  • Configurable vision model — choose from pinned local or provider-capable Vision Quick Choices, including ChatGPT / Codex, Claude Subscription, and xAI Grok OAuth rows whose catalog metadata or runtime probes report image input support
  • Camera selection — pick which camera to use when multiple devices are present
  • Inline image display — captured and workspace images are shown inline in chat
  • Provider vision support — provider models with image capability are auto-detected and work alongside local vision models; Quick Choice refresh preserves provider-specific Vision metadata instead of downgrading rows through generic text-only heuristics, and xAI Grok OAuth can record a provider-specific vision probe result
  • Atlas Cloud vision boundary — Atlas-hosted multimodal chat models can be used for Vision when classified as image-capable, but Atlas image-generation and video-generation catalog rows are not exposed through Vision or Brain model surfaces
  • Media-model boundary — Grok Imagine image/video rows are kept on Image and Video surfaces, not Vision or Brain surfaces, even when they come from the same xAI account
  • Computer Use fallback boundary — native Computer Use may request Vision only for an ephemeral target-window screenshot when accessibility data is insufficient; the configured Vision provider and local/cloud status remain explicit

Workflows & Scheduling

Tasks have been renamed to Workflows throughout the application. The workflow engine adds a step-based pipeline runner, delivery routing, approvals, triggers, and safety gating on top of APScheduler.

Core Engine

  • Unified workflow engine — named multi-step workflows run sequentially in a fresh or persistent thread and are scheduled through APScheduler
  • SQLite schema recovery — tasks.py validates the workflow database schema before use, repairs partial schemas in place, backs up and recreates corrupt DBs, and retries schema-related operations once after repair
  • 7 schedule types — daily, weekly, weekdays, weekends, interval, cron, and one-shot delay_minutes
  • Template variables — prompts can use {{date}}, {{day}}, {{time}}, {{month}}, {{year}}, {{task_id}}, and {{step.X.output}}
  • Per-workflow model/profile override — each workflow can force a different model or Agent Profile, then restore the default after completion
  • Skills and tools overrides — workflows can narrow the skill set globally and the tool set per step; promoted Agent-run workflows preserve the originating profile and safety context for review before enablement
  • Channel delivery — workflow output can inherit the workflow-level default delivery channels or use a per-workflow override via delivery_channel and delivery_target; web-app run status is always preserved
  • Persistent threads — workflows can reuse the same thread across runs to preserve context
  • Notify-only mode — workflows can skip agent execution and just send notifications
  • Webhook triggers — workflows can be launched by HTTP webhook with per-workflow secrets
  • Completion triggers — one workflow can trigger another after finishing
  • Concurrency groups — related workflows can be serialized so only one runs at a time
  • Safety mode — block_destructive, require_approval, and allow_all modes control shell, workflow, and channel behavior inside background execution

Step-Based Pipelines

  • 5 step types — Prompt, Condition, Approval, Subtask, and Notify
  • Conditional branching — condition steps support contains, not_contains, regex, json_path, and llm_evaluate, each with if_true / if_false targets
  • Approval gates — approval steps pause execution, route requests through channels and desktop notifications, and resume on explicit user approval or denial
  • Prompt chaining — each step can see previous step output, enabling research → summarize → act patterns
  • Agent-callable workflows — the task tool can create, update, and run full step graphs programmatically
  • Agent-run promotion — completed child-agent runs can be promoted into disabled manual workflows, preserving the original objective, context summary, profile reference, skills/tools overrides, model override, and approval mode so the workflow can be reviewed before scheduling or enabling

Workflow Builder UI

  • Simple/Advanced toggle — simple mode preserves a single-prompt workflow editor; advanced mode exposes the full step builder
  • Mobile simple editor — ui/mobile_workflows.py provides a full-screen phone editor for safe workflow metadata, prompt steps, schedules, profiles, model overrides, approval policy, persistent threads, channel delivery, and enablement; advanced graph steps are preserved and left for desktop editing
  • Step builder — reorder, delete, retarget, and retype steps visually
  • Variable insertion menu — context variables and prior-step outputs can be inserted without hand typing placeholders
  • Flow preview — Mermaid diagram generated from the step graph with manual refresh
  • Validation — required-field checks, reference validation, and operator-specific rules run before save
  • Delivery defaults UI — the Workflows panel exposes a compact default-delivery selector; workflows tied to default update when the global default changes, while explicit overrides remain untouched

Approval System

  • Pending approvals panel — approval cards show task or child-agent source, a bounded display-safe reason, request text, and Approve / Deny controls
  • Sidebar badge — pending approvals surface as a badge and quick actions above the thread list
  • Multi-surface routing — approvals can be routed through desktop, the mobile Activity surface, Telegram, Discord, Slack, WhatsApp, SMS, and plugin-owned channel paths according to channel capabilities; button-capable adapters render inline controls and text-only adapters require an explicit YES/NO response
  • Resume integration — the agent and workflow runtime resume correctly on approve or deny and follow the appropriate branch

Workflow Console

  • Right-side console — ui/command_center.py exposes running work, active goals, child-agent runs, approvals, upcoming runs, quick launch actions, recent history, and insights in one drawer
  • Collapsible layout — console expansion state persists in browser and pywebview; collapsed state shows compact running/approval/insight badges and attention styling when an approval is waiting
  • Live operational view — running workflows, goals, child-agent states, background states, and recent outcomes stay visible while you continue chatting elsewhere in the app
  • Insight actions — insight cards support pin, dismiss, and apply actions directly from the console
  • Journal access — extraction and dream journals are accessible from the same workflow-centric monitoring surfaces

Existing Features

  • Always-background execution — workflows run without blocking the main chat UI
  • Pre-built templates — seeds five disabled starter workflows across simple and advanced examples; nothing is scheduled or run until the user enables it
  • Home screen dashboard — Workflows and Activity tabs show tiles, upcoming runs, run history, channel status, pending approvals, extraction journal, and dream journal
  • Persistent run history — execution history survives workflow deletion for auditability
  • Monitoring / polling — interval schedules plus condition steps support ongoing monitors like price checks or release watchers
  • Stop / cancel support — running workflows can be stopped from the chat header, activity panel, or workflow card

Designer Studio

Designer Studio is Row-Bot's dedicated visual-authoring subsystem. It spans five distinct project modes, a sandboxed interactive runtime, an authoring guardrail stack, and a mutation-reviewable tool surface for editing projects turn over turn.

Project Modes

Every project is created in one of five modes. Each mode carries its own canvas presets, template gallery, prompt budgets, critique rules, runtime behavior, and export targets.

  • deck — traditional slide decks; 16:9 canvas; ≤5 bullets per slide; PPTX export via python-pptx preserves editable text runs, images, and charts
  • document — long-form report / one-pager pages; A4 or letter canvas; 130–160 words per block; PDF export is the primary delivery format
  • landing — interactive marketing landing pages; vertical scroll canvas; CTAs and multi-section hero / feature / pricing layouts; published as interactive HTML
  • app_mockup — multi-screen app prototypes; route-aware navigator so the agent can define screens and declarative navigation between them; runtime bridge turns link / button clicks into in-preview route changes
  • storyboard — motion / ad storyboards; limited to 3–4 blocks per frame to avoid cropping; pairs naturally with the video generation tool for per-frame motion references

Interactive Runtime

Interactive modes (landing, app_mockup, storyboard) do not allow free-form <script> from the agent. Behavior is expressed declaratively via data-row-bot-action attributes and interpreted at runtime by a sandboxed bridge.

  • designer/runtime/ package — loads per-project runtime state, resolves route / screen navigation, handles state toggles, controls media playback, and dispatches declarative actions to real DOM operations inside the preview iframe
  • Declarative action grammar — data-row-bot-action="navigate:screen-id", data-row-bot-action="toggle:state-key", data-row-bot-action="play:asset-id", etc. — the agent authors intent, the runtime executes it safely
  • Shared preview + publish runtime — the same runtime powers editor preview, presenter mode, and published share links so interactive projects behave identically in all three surfaces

Project Model & Storage

  • Multi-page / multi-screen projects — each project stores a page list, canvas dimensions, aspect ratio, mode, title metadata, notes, brand settings, and (for app mockups) a route map
  • Home gallery — the Home screen includes a dedicated Designer tab with recent projects, new-project flows, and quick reopen actions
  • Canvas presets and resizing — projects can be resized after creation; mode-appropriate presets are offered up front
  • Reference storage — uploaded briefs, screenshots, and source material are stored as reusable references so future designer sessions can reopen them without reuploading
  • Asset-backed media — project HTML stores media as asset://<asset-id> references rather than brittle placeholder tokens; designer/render_assets.py normalizes legacy refs, preserves data-asset-id, and hydrates assets for preview, presentation, export, and published output
  • Persistent asset storage — designer assets live on disk under ~/.row-bot/designer/assets/; projects and references are stored separately
  • Windows-safe writes — designer/storage.py uses temp-file + replace semantics with retry logic to avoid broken saves on Windows file locks

Editor & Authoring

  • Full-width editor — designer/editor.py switches the app into a full-width editing mode with page / screen navigator, preview, controls, and assistant side chat
  • Shared chat primitives — the designer editor reuses ui/chat_components.py so uploads, input behavior, and chat rendering match the main conversation UI
  • Surgical tool surface — the designer tool can set, update, add, move, duplicate, and delete pages / screens; move, replace, restyle, and remove individual elements; refine-text-in-place (shorten / expand / simplify / rewrite); insert reusable components; update brand settings; and resize projects
  • Setup flow — the creation flow captures mode, format, audience, tone, and source brief before generating an initial draft
  • Typed image slots — templates declare expected image slots by semantic role (hero, thumbnail, icon, background, etc.) so generated imagery lands in intentional places with appropriate aspect ratios
  • Reusable components — curated insertable blocks like heroes, stat bands, timelines, testimonials, pricing sections, and app shells accelerate common layouts
  • Authoring guardrails — mode-specific content budgets, no-decorative-overlap rules, horizontal button-row rules, and slot-typed imagery are encoded in designer/prompt.py so the agent produces layout-clean output on first draft

Critique & Repair Loop

  • designer/critique.py — runs deterministic checks for overflow, card-heavy sections, contrast, hierarchy, readability, and spacing on any page
  • Mandatory post-edit critique — the designer tool automatically critiques after each structural change and applies safe repairs before returning control to the agent
  • Repair operations — deterministic, side-effect-scoped fixes (e.g. trim overflowing blocks, drop redundant bullets, fix contrast, respace buttons)
  • Review dialog — a mutation diff view shows exactly what the agent changed on each turn, per page, so the user can accept, revert, or spot-check without hunting through the project

AI Content

  • AI image generation — generate slide / page imagery directly inside the designer workflow, routed into typed image slots
  • AI video generation — storyboard frames and landing hero videos can be generated via the video_gen_tool and referenced as asset:// media
  • Chart insertion — create charts from inline CSV and place them in a page layout
  • Speaker notes — generate and persist notes for presenter use

Presentation, Sharing & Export

  • Presenter mode — designer/presentation.py serves Reveal.js-based presenter mode with notes support (deck mode)
  • Export pipeline — Playwright drives raster + HTML export; python-pptx drives editable PPTX; weasyprint / Playwright drive PDF; PNG exports for any page
  • Published share links — self-contained interactive HTML (with runtime bridge) is mounted under /published for direct sharing

Developer Studio

Developer Studio is Row-Bot's code-workspace subsystem. It is not a full IDE; it is a Codex-style agent workbench for connecting local Git repositories, reviewing code, making scoped edits, running tests, preparing branches/commits/PRs, and keeping the user in control through approval modes and an inspector.

Workspace Model

  • developer/ package — owns workspace storage, Git helpers, worktree allocation, runtime profiles, approval policy, sandbox state, tool context, todos, change ledger, inspector snapshots, GitHub helpers, and UI
  • Explicit repo linking — users open an existing local repo or clone into a folder they choose. Row-Bot stores a workspace link and metadata, not a copy of the repo in app data
  • Code threads — Developer conversations are tagged as code threads and reopen directly into Developer Studio with the associated workspace context
  • Developer worktrees — developer/worktrees.py allocates durable Git worktrees for threads, child-agent runs, and workflow runs, tracking owner kind/id, project workspace, worktree workspace, branch name, base branch/commit, cleanup state, metadata, and failure preservation in tasks.db
  • Worktree seeding — worktrees can start from the current staged/unstaged/untracked state or from the last commit; seed application uses binary Git patches and safe untracked-file copying while requiring a real repository root
  • Workspace context injection — Developer turns receive compact hidden context with repo path, branch, dirty state, remote URL, top-level files, approval mode, execution mode, shell guidance, and sandbox state
  • No user-message leakage — Developer context is injected as model context and is not rendered as part of the visible user message

Approval Modes & Tooling

  • Mode-specific policy — read-only, ask-before-changes, auto-edit, and agent-run modes control file writes, shell commands, Git operations, commits, pushes, and PR preparation
  • Native Developer tools — tools/developer_tool.py exposes workspace-scoped operations for repo info, file listing, reads, search, git status, diffs, todos, detected tests, shell commands, patch preview/apply, file writes, branch create/switch, commit, push, fast-forward merge, sandbox imports, and safe revert of agent-owned changes
  • Shell remains available — Developer-native tools are preferred for repo work, but shell is still available for legitimate project commands and follows Developer approval policy
  • Shared checkpointed work budget — Developer turns use the application-wide model-iteration setting and preserve workspace state, todos, and diffs when a budget or fallback framework guard ends the turn, so the user can continue from the current checkpoint
  • Tool guide and skills — the Developer tool guide plus Developer coding/review/PR/custom-tool skills are injected for Developer context without bloating normal chat by default

Inspector & Live State

  • Developer Inspector — the right-side inspector shows Overview, Safety Policy, Sandbox, Todos, Changes, Files, Agent Changes, Tests, and GitHub/PR sections
  • Debounced snapshots — developer/inspector_snapshot.py builds lightweight snapshots that the UI can apply without fully rebuilding the chat transcript
  • Resizable panel — the inspector can be widened for diffs, files, and test output
  • File tree — Files render as a repo tree instead of a flat list, with generated/build/cache paths filtered out
  • Change ledger — developer/change_ledger.py tracks agent-owned edits, line counts, diffs, and revert eligibility
  • Todo persistence — developer/todos.py stores visible coding plans so long-running work can show current, pending, and completed steps

Docker Sandbox

  • Execution modes — Local runs commands in the selected repo folder; Docker Sandbox runs commands in an isolated shadow copy
  • Persistent sandbox container — developer/sandbox_runtime.py manages a per-workspace container and shadow workspace so repeated commands share sandbox state until rebuilt or cleaned
  • Import-gated edits — sandbox changes become pending patches and only modify the real repo after explicit import
  • Network policy — Docker Sandbox supports network off, ask, or on. Network/package-install attempts are blocked early when network is off and approval-gated when policy requires it
  • Image selection — workspaces can choose a Docker image; changing the image cleans the sandbox copy before the next Docker command
  • Local fallback — users who do not want Docker keep using local execution under the same Developer approval model
  • Clear startup errors — stopped Docker, missing local images, and Docker credential-helper problems are reported as actionable sandbox errors

GitHub & PR Flow

  • GitHub CLI detection — developer/github.py and developer/executables.py locate gh from common install paths, especially on Windows where PATH can differ between the app and a shell
  • PR helpers — branch, commit, push, and PR-prep tools are approval-gated and operate inside the selected workspace
  • No hidden remotes — cloning asks for an explicit destination, and push/PR operations are visible through the active approval mode

Custom Tools

Custom Tools let users convert a GitHub repo, local folder, or current Developer workspace into reusable Row-Bot tools without editing manifests by hand.

Product Surface

  • Developer home surface — Custom Tools live under Developer as a global area separate from workspaces, with cards for created tools, source, install path, command count, enablement, test output, and removal
  • Wizard flow — the guided flow is Source -> Inspect -> Test -> Enable. Users can review proposed commands, run a smoke test, then choose whether the tool is only available in Developer or promoted to normal chat
  • Conversational builder — tools/custom_tool_builder_tool.py exposes one compact agent-facing tool for clone/source setup, draft creation, command refinement, testing, creation, promotion, disable, and removal
  • Source setup hardening — clone, folder, and current-workspace flows normalize install paths, reuse Developer storage, and keep Git/virtualenv setup errors visible instead of leaving half-created tools
  • Settings integration — the Custom Tool Builder appears as a Utilities toggle. Disabling it removes the builder from normal chat while keeping the Developer UI available for manual management

Command Generation & Validation

  • developer/tool_capsules.py — retained internal module name for compatibility; user-facing copy says Custom Tool
  • LLM-assisted proposals — a lightweight model pass inspects repo files and README content to propose useful, preferably read-only commands. Deterministic fallback remains available if AI analysis fails
  • Draft management — the builder stores draft IDs so users can review and refine proposed commands across turns before creating the tool
  • Command classification — commands are tagged by locality/risk and validated for dangerous shell patterns, unreviewed network behavior, write operations, missing placeholders, and malformed command templates
  • Environment validation — generated commands are smoke-tested against the selected source tree and virtualenv/runtime assumptions before promotion, with failure details preserved for review
  • One-time tests — local/read-only tests can run directly; network or riskier tests route through the normal approval mechanism
  • Promotion — promoted Custom Tools register as synthetic plugin-style tools, inherit normal tool enablement, and can be disabled or removed without deleting the source repo

Trust Boundaries

  • Source transparency — cards show source URL, local install path, version, command count, and availability
  • No automatic broad enablement — generated tools are opt-in and are not silently made available to normal chat
  • Repo code is not trusted by default — proposed commands are reviewed and tested before promotion; users should only promote tools whose behavior they understand

Row-Bot Status & Identity

Row-Bot now has a formal self-inspection and self-management surface: a tool for querying its own state, a controlled settings mutation API, and a Preferences UI for identity and self-improvement.

Status Queries

  • row_bot_status tool — read-only introspection across overview, version, model, agents, channels, memory, skills, tools, mcp, providers, insights, evolution, api_keys, identity, tasks, vision, image_gen, video_gen, voice, config, logs, errors, updates, and designer
  • Live runtime visibility — the tool can report current model/provider, catalog/cache status, provider readiness, active goals, Agent Profiles, child-agent runs, delegation capacity and work-round progress, active channels, knowledge graph counts, enabled and pinned skills, configured APIs, task state, voice/image/video settings, and designer project counts
  • Diagnostics access — recent warnings, provider/runtime probe failures, status-tray findings, errors, and tracebacks can be summarized without opening log files manually
  • Home health bar parity — ui/status_checks.py and ui/status_bar.py expose compact health checks for Ollama, active model, cloud API, tunnel, OAuth accounts, workflows, goals, agents, knowledge, wiki vault, documents, search, skills, tracker, Buddy, MCP, plugins, Computer Use, network, tools, disk, threads DB, FAISS, Dream Cycle, TTS, and logging

Controlled Self-Management

  • row_bot_update_setting — approved mutations for Brain and Vision model switching, assistant name, personality, context caps, dream-cycle controls, skill toggles, skill pins, tool toggles, image-generation model, video-generation model, manual dream-cycle trigger, and self-improvement toggle
  • Agent and media diagnostics — status output includes Agent Profile/child-run summaries and provider-aware media rows so xAI Grok OAuth, direct xAI, Google, and OpenAI media availability can be diagnosed without opening Settings
  • Interrupt-gated writes — all state-changing operations route through explicit user confirmation before they are applied
  • Controlled proposal tools — when self-improvement is enabled, row_bot_create_skill, row_bot_patch_skill, row_bot_send_feedback, row_bot_apply_proposal, row_bot_reject_proposal, row_bot_verify_proposal, and row_bot_review_skill_library operate through the controlled self-evolution store instead of directly mutating state
  • Skill patch safety — bundled skills are patched via user-space overrides, not in-place mutation; old versions are backed up under ~/.row-bot/skill_versions/

Identity & Preferences

  • identity.py — stores assistant name, personality text, and self-improvement flag; sanitizes personality input before save
  • Preferences tab — Settings exposes name, personality, preview, and self-improvement controls in one place
  • Prompt integration — the same identity settings are consumed by self_knowledge.py so the opening line seen by the model matches what the user configured
  • Parallel UI surface — the Home health/status bar provides a visual health view for the user, while row_bot_status exposes the same class of state to the agent

Self-Knowledge & Insights

Row-Bot now carries an explicit self-description into prompts and uses Dream Cycle to turn recent activity into structured insight objects.

Prompt-Time Self-Knowledge

  • Feature manifest — FEATURE_MANIFEST in self_knowledge.py is the canonical inventory of major capabilities used when Row-Bot explains what it can do
  • Dynamic identity line — build_identity_line() combines the configured assistant name and personality into the opening identity sentence
  • Dynamic state block — build_self_knowledge_block() appends live state like current model, configured providers, entity count, last dream summary, active channels, designer project count, and enabled skills
  • Prompt injection — the self-knowledge block is added alongside tool, memory, and citation guidance so the model can talk about itself accurately without outdated copy in prompts.py

Insight Generation & Triage

  • Dream snapshot analysis — Dream Cycle phase 5 captures logs, provider/model/media configuration, usage signals, and active insights, then runs DREAM_INSIGHTS_PROMPT
  • Structured insight store — insights.py persists categorized insights like error_pattern, skill_proposal, tool_config, knowledge_quality, usage_pattern, and system_health
  • Dedup and pruning — similar titles and semantically overlapping insights are merged; stale insights are auto-pruned; last-analysis time is tracked
  • Pin / dismiss / apply actions — the Workflow Console exposes user actions for curating the insight list without leaving the app
  • Skill proposals — insight objects can carry draft skill metadata, which pairs naturally with the self-improvement toolchain when enabled

Controlled Self-Evolution

Controlled self-evolution turns insights, repeated user workflows, and explicit self-improvement requests into reviewable proposals. It is intentionally not an autonomous code-rewrite loop: the system records intent, previews the effect, asks for approval before mutating anything, writes audit records, and keeps rollback metadata where mutation is allowed.

  • evolution.py engine — owns proposal creation, validation, status transitions, action runs, rejection memory, curator reports, feedback reports, and persistence under ~/.row-bot/controlled_evolution.json
  • Proposal lifecycle — proposals move through draft, ready, approved, applied, verified, rejected, or failed; terminal proposals are retained for audit and duplicate-suppression instead of being discarded
  • Proposal types — supported proposal types include investigate, create_skill, patch_skill, consolidate_skills, send_feedback, settings_change, and memory_correction; only a subset performs mutation in this release
  • Insight mapping — Dream Cycle insights map to proposal types based on category, severity, and whether the issue is a repeated user-facing workflow or a system/provider maintenance concern
  • Investigation threads — investigation proposals create draft threads with durable prompts so the user can inspect and continue diagnostic work before any state change
  • Skill mutation bounds — skill creation and patch proposals validate names, block tool-guide mutation, reject likely secrets, cap diff size, back up prior versions, and apply only after approval
  • Feedback reports — send-feedback proposals produce redacted local Markdown reports and support links without silently posting to a remote service
  • Curator dry-runs — skill-library review can detect overlapping or stale skills and create proposals without mutating skill files
  • Status and UI integration — row_bot_status exposes the evolution category, proposal action tools, recent action runs, rejection memory, and curator dry-runs; Command Center/insight surfaces can display proposal rows next to their originating insight
  • Rejection memory — rejected proposals are remembered with fingerprints so similar future proposals can cite the prior rejection instead of recreating the same suggestion blindly

Messaging Channels

Row-Bot uses a generic Channel abstraction. Native adapters and plugin-owned channels declare capabilities and register through controlled runtime paths. The system then auto-generates tools, settings UI, monitoring, and approval routing around that channel.

Channel Architecture

  • Channel ABC — adapters implement lifecycle methods (start, stop, is_configured, is_running) plus outbound send methods for text, photos, documents, and approval requests
  • ChannelCapabilities — declarative feature flags describe what each channel supports: photos, documents, voice, buttons, streaming, typing, reactions, and commands
  • Config schema — each channel declares config fields so Settings can render the right form dynamically
  • Channel registry — adapters self-register; runtime helpers expose all channels, running channels, configured channels, and delivery routing
  • Channel credential store — channels/auth_store.py stores channel secrets through a channel-specific OS keyring path with legacy fallback so running channels survive migrations even if UI fields are intentionally blank
  • Shared media pipeline — inbound audio transcription, image analysis, document extraction, inbox persistence, and workspace copy helpers are centralized in channels/media.py
  • Shared utilities — auth, command handling, goal/profile-aware runtime context, approval routing, media capture, and corrupt-thread repair live in reusable channel modules
  • Plugin channel bridge — plugin-owned channels use plugins/channel_runtime.py to route inbound text, attachments, approvals, Goal Mode continuation, generated files, typing/stream callbacks, and thread metadata through the same core channel runtime without importing Row-Bot internals
  • Tool factory — running channels contribute auto-generated send/photo/document tools through channels/tool_factory.py
  • Activity tracking — per-channel last-activity timestamps drive the sidebar monitor and status surfaces
  • Shared streaming engine — channels/streaming.py consumes token, thinking, tool, interrupt, error, and done events; coalesces partial updates by time and character thresholds; sends typing keepalives; caps overflow previews; retries bounded rate limits; splits platform-safe finals; and falls back to a fresh final send when an edit cannot be finalized
  • Transport-local capabilities — channel adapters implement only start/update/final/cleanup/split primitives while the shared engine owns cadence, finalization, fallback, cancellation, and delivery results
  • Checkpoint persistence — successful channel delivery repairs a human-only checkpoint with the assistant answer but detects and preserves graph-written assistant messages to avoid duplicates
  • Durable thread notifications — channels/thread_notifications.py stores once-only child-agent and Goal Mode terminal notices, retries failed delivery after channel startup, and suppresses notices for wait-mode results already consumed by the parent

Bundled Channels

  • Telegram — full agent access, native draft streaming in supported private chats with edit fallback, UTF-16-aware message splitting, voice transcription, photo analysis, document extraction, emoji reactions, inline approval buttons, /model support, and HTML-safe formatting
  • WhatsApp — Baileys bridge with QR pairing, inbound/outbound media, rich YouTube previews, Markdown-to-WhatsApp formatting, edit streaming, typing updates, split finals, and approval resume
  • Discord — DM-based edit streaming with typing keepalive, message splitting, fresh-send fallback, reactions, interactive approval buttons, slash-command integration, and media support
  • Slack — Socket Mode adapter with native stream APIs when supported, edit fallback, bounded retry-after handling, DM threading, Block Kit approvals, reactions, and file uploads
  • SMS — Twilio adapter with inbound webhook support, outbound SMS/MMS, tunnel-manager integration for public callbacks, message-safe final splitting, and YES/NO approvals; streaming remains off because SMS has no editable partial-message contract

Delivery & Monitoring

  • Auto-generated channel tools — when a channel is running, the agent gains send/photo/document tools for that channel automatically
  • Approval routing — approvals can be sent through supported channels with inline action controls
  • Goal and profile context — channel-triggered turns carry thread goal/profile context into the normal agent path so Goal Mode and Agent Profile behavior are consistent outside the desktop UI
  • No duplicate finals — normal turns, Goal Mode callbacks, approval resumes, and plugin-channel turns share a delivery result contract so a successfully streamed final is not sent again by legacy completion code
  • Cancellation behavior — cancelled streams clean previews and return a non-finalized delivery result instead of persisting or announcing a false success
  • Sidebar channel monitor — the conversation sidebar shows live status dots, icons, display names, and relative last-activity timestamps
  • Auto-start and config persistence — channel enablement and settings persist to ~/.row-bot/channels_config.json

Tunnel Manager

A provider-agnostic tunnel layer exposes local webhook ports to the internet when a channel needs inbound delivery.

  • Provider abstraction — TunnelProvider defines the backend contract; NgrokProvider is the current implementation
  • TunnelManager singleton — manages tunnel lifecycle, per-port allocation, cleanup, and status reporting
  • Automatic use by channels — channels that need a public callback request a tunnel on start and release it on shutdown
  • Optional app tunneling — the main Row-Bot UI can also be exposed intentionally for paired mobile access; public ngrok URLs still terminate at the mobile access gate rather than bypassing device authentication
  • Tailscale discovery boundary — mobile/tailscale.py detects optional Tailscale direct and Serve routes without making Tailscale a tunnel-provider dependency; Mobile Access prefers a reachable private route before an existing public ngrok tunnel
  • Settings UI — tunnel provider, auth token, and active-tunnel status live in the System settings surface
  • Health checks — tunnel status participates in the status monitor and diagnostics flows

X (Twitter) Tool

Row-Bot integrates with X API v2 through a native httpx-based client, grouped into three high-level tool entry points.

  • 3 grouped LangChain tools — x_read, x_post, and x_engage
  • Read operations — search, read tweet, timeline, mentions, and user info
  • Post operations — post tweet, reply, quote, and delete tweet
  • Engagement operations — like, unlike, repost, unrepost, bookmark, and unbookmark
  • OAuth 2.0 PKCE — browser-based auth flow with a local callback server and refresh-token support
  • Rate-limit tracking — per-endpoint rate information is recorded and surfaced in structured error responses
  • Tier discovery — X tier information is persisted and reused for rate-limit expectations
  • Local token storage — auth state lives in ~/.row-bot/x/
  • Settings UI — connect, disconnect, and inspect X auth from Accounts settings

Tool Guides

Tool guides are lightweight SKILL.md packages that attach contextual instructions to tools without hard-coding those instructions into the main system prompt.

  • Skill-like format — each guide is a directory with a SKILL.md file and YAML frontmatter, just like a manual skill
  • tools: activation field — guides declare the tools they apply to; when any linked tool is in the active tool belt, the guide is injected automatically
  • Prompt injection — prompts.py discovers active guides and appends them to the system prompt at runtime
  • Invisible to the manual skill toggles — tool guides are auto-managed and do not clutter the user-facing skill list
  • 22 bundled guides — Agents, Browser, Calendar, Chart, Custom Tool Builder, Designer, Developer, Email, Filesystem, Goal, Math, MCP, Shell, Telegram, Row-Bot Status, Tracker, Updater, Video, Vision, Weather, Wiki, and X
  • Consistency benefits — guide content can evolve independently of the main prompt, reducing drift and duplicated instructions

Skills Hub & Skill Activation

Skills Hub is the discovery, import, search, and installation layer for manual skills. It sits above the lower-level skills.py loader and skills_activation.py runtime selection path: Skills Hub gets skills into the local library, while Smart Skills decides which enabled skills should shape a given turn.

  • Manual skill library — user-installed skills live under ~/.row-bot/skills/<name>/SKILL.md and use the same YAML-frontmatter package shape as bundled skills
  • Pinned skill defaults — skills.py tracks pinned manual skills separately from one-off composer choices so default skills can stay available across sessions without forcing every enabled skill into every prompt
  • Smart activation — skills_activation.py resolves enabled skills, explicit /skill requests, draft suggestions, per-thread overrides, and workflow overrides before prompt assembly
  • Slash commands — slash_commands.py provides skill-aware chat commands such as using, disabling, or narrowing skills without leaving the conversation
  • Shared composer controls — ui/chat_composer_extras.py gives main chat, Designer Studio, and Developer Studio a common slash palette, skill picker, skill chips, and draft-suggestion path
  • Source adapters — skills_hub/ can inspect GitHub repositories, pasted Markdown, direct URLs, well-known skill indexes, and marketplace-style catalogs before installation
  • Import detection — pasted or linked content is classified before install so a raw SKILL.md, a folder-like package, or a catalog entry can route through the right importer
  • Search index — local and remote catalog rows are normalized into searchable records with source, tags, description, install state, and provenance metadata
  • Provenance and safety — installed skills retain origin/source metadata, user overrides take precedence over bundled skills, and user-controlled enablement determines whether manual skill instructions enter the system prompt
  • Testing coverage — tests/test_skills_activation.py, tests/test_skill_pinning.py, tests/test_slash_commands.py, tests/test_skills_hub.py, tests/test_skills_hub_sources.py, tests/test_skills_hub_search.py, and UI/source tests cover activation, pinning, import detection, source adapters, search, and composer contracts

Image Generation

Row-Bot can generate and edit images through multiple external providers, render them inline, persist them to disk, and reuse them in designer workflows or channel delivery.

  • Provider support — OpenAI image models, xAI Grok Imagine through direct API keys or xAI Grok OAuth, Google Imagen 4, and Gemini image-capable models
  • Generate and edit flows — prompts can generate a new image or edit the most recent image, an attached image, or an on-disk file
  • Inline rendering — generated images are surfaced directly in the chat stream without requiring a separate viewer
  • Per-thread persistence — generated images are saved into Row-Bot's media storage so they survive refreshes and can be referenced later
  • Channel delivery — running messaging channels can pick up generated images and send them as photos
  • Designer reuse — Designer Studio can invoke the same provider layer for slide assets and visual content generation
  • Settings selector — the active image-generation model is configurable from Settings and queryable through row_bot_status
  • Provider boundary — Atlas Cloud media-generation catalog rows are intentionally not exposed as image-generation choices in this phase; xAI Grok Imagine rows are exposed only when the direct xAI API key or xAI Grok OAuth runtime is available

Video Generation

Row-Bot can generate short video clips from text prompts or reference images through Google Veo and xAI Grok Imagine Video for chat use and Designer storyboard workflows.

  • video_gen_tool — top-level agent tool for text-to-video and image-to-video generation
  • Provider support — Google Veo handles text-to-video and image-to-video with provider-side person-generation policy handling; xAI Grok Imagine Video supports text-to-video and image-to-video through direct xAI API keys or xAI Grok OAuth with provider-specific aspect ratio, duration, and resolution constraints
  • Inline rendering — generated clips are surfaced directly in the chat stream with safe media-element hydration
  • Designer integration — Designer Studio storyboards and landing hero slots can reference generated videos as asset:// media; motion clips are rendered in preview, presenter mode, and published share links
  • Persistent asset storage — generated clips are saved to Row-Bot's media storage so they survive thread refreshes and can be reused across designer projects
  • Channel delivery — running messaging channels can pick up generated videos and deliver them where supported
  • Provider boundary — Atlas Cloud video-generation catalog rows are intentionally not exposed as video-generation choices in this phase; Grok Imagine Video rows are exposed only on Video surfaces and do not leak into chat, agent, or Vision model pickers

MCP Client & External Tools

Row-Bot includes a guarded Model Context Protocol client that can connect external MCP servers and expose their tools to the ReAct agent without making external servers part of Row-Bot's trusted core.

Runtime Model

  • Dedicated package — mcp_client/ owns persistent config, marketplace search, dependency checks, safety classification, runtime sessions, logging, result normalization, and curated starter metadata
  • Separate config file — MCP state is stored in ~/.row-bot/mcp_servers.json, separate from native tool toggles, so malformed or broken MCP config falls back to an empty disabled config instead of damaging normal tool settings
  • Global enable switch — enabled in MCP config is the top-level kill switch. Turning it off stops active sessions, clears the discovered catalog, removes dynamic MCP tools from the agent, and keeps saved server definitions for later
  • Per-server runtime — each enabled server gets its own McpServerRuntime session tracked by status (connecting, connected, failed, dependency_missing, stopped, global_disabled), tool counts, timestamps, transport, and last error
  • Transport support — stdio, Streamable HTTP, and SSE are supported through the Python MCP SDK. Each server can set command, args, cwd, env, URL, headers, connect timeout, tool timeout, and output limit
  • Non-blocking startup — app.py discovers enabled servers during startup in a guarded path. Exceptions are logged as warnings and do not stop Row-Bot from launching
  • Failed-until-refresh state — a failed enabled server is not restarted on every discovery pass; it remains failed until the user explicitly refreshes it or changes configuration
  • Generation-aware waits — probe and tool-call futures poll the active cancellation scope so Stop cancels the pending future and normalizes the result instead of leaving a generation blocked
  • Shutdown cleanup — app shutdown calls MCP runtime shutdown to close child sessions and stop external stdio processes

Dynamic Tool Injection

  • Parent registry tool — tools/mcp_tool.py registers mcp / External MCP Tools as the native parent tool. It is the stable toggle users see in Settings and Row-Bot Status
  • Dynamic wrappers — discovered enabled MCP tools are converted into LangChain StructuredTool instances at agent build time, with names generated as mcp_<server>_<tool>
  • Immediate cache invalidation — MCP add/edit/delete, global/server enablement, tool enablement, and approval-policy changes clear the loaded agent cache so the next graph sees the new external tool surface
  • Schema conversion — JSON input schemas are converted into Pydantic argument models where possible, with a permissive fallback for complex or invalid schemas
  • Resources and prompts — servers can optionally expose list_resources, read_resource, list_prompts, and get_prompt utility tools through per-server advanced toggles
  • Readable display names — agent.py resolves tool-call UI labels back to the original MCP tool and server name, for example MCP: microsoft_docs_search (microsoft-learn-mcp)
  • Result normalization — MCP text, structured content, resource links, embedded resources, binary/image blocks, empty results, errors, and oversized outputs are normalized before being sent back into the model

Safety & Trust Boundaries

  • External output is untrusted — the MCP tool guide tells the agent not to follow instructions found inside MCP results unless they are clearly part of the user's request
  • Native tools stay preferred — Row-Bot Memory, Browser, Computer Use, filesystem, document, search, channel, and Designer capabilities remain canonical for Row-Bot-owned behavior; overlapping MCP servers are treated as external alternatives
  • Destructive classification — tool names, descriptions, and MCP annotations are inspected for write/send/delete/run/deploy/payment-style behavior. Destructive tools require approval and are not enabled by default after discovery
  • Approval synchronization — destructive MCP wrapper names are included in the parent tool's destructive_tool_names, so they flow through the existing interrupt approval mechanism
  • Background workflow rules — MCP destructive tools follow workflow safety mode: approval-required modes interrupt, while explicit allow-all mode can run enabled destructive MCP tools
  • Capability overlap detection — mcp_client/conflicts.py labels MCP servers that overlap native memory, browser, documents, web search, URL reading, channels, or Designer capabilities and forces manual tool selection for overlap/high-risk imports
  • Secret masking — diagnostics use masked config output so headers, tokens, and environment values are not displayed raw

Settings UI & Marketplace

  • Settings → MCP — ui/mcp_settings.py provides the user-facing MCP control surface: global enable switch, add server, import config, browse MCP servers, diagnostics, test, refresh, edit, delete, and per-tool controls
  • Disabled-until-tested imports — manual JSON imports and marketplace entries are saved disabled. Users test the server before enabling it
  • Tool review rows — after a successful probe, each tool shows name, description, input schema summary, enabled state, destructive badge, approval state, and whether it comes only from saved config or live catalog
  • Marketplace adapters — mcp_client/marketplace.py can search curated starters plus official-style directories, PulseMCP, Smithery, and Glama, with cache and curated fallback when live results fail or ignore the query
  • Starter metadata — curated entries preserve trust tier, risk level, auth requirement, native overlap, requirements, notes, and install recipe metadata
  • Xquik starter — the curated Xquik streamable-HTTP entry documents its x-api-key header, X/Twitter search/extraction/monitoring capabilities, and high-risk generic executor; private reads, writes, persistent monitors/webhooks, and metered actions remain approval-gated
  • Marketplace edit preservation — editing an installed catalog server retains its source/catalog metadata while updating runtime fields, so origin, risk, and install context do not disappear after local configuration changes
  • Diagnostics dialog — Settings can display masked MCP config and live status summary for support/debugging without requiring file edits

Runtime Requirements

  • Requirement inference — stdio launch commands infer runtime requirements for npx/Node.js, uvx/uv, Docker, and Playwright MCP browser dependencies
  • Managed user-space installs — Row-Bot can install private Node.js LTS, uv, and Playwright Chromium runtimes under ~/.row-bot/runtimes/ and inject those paths only into MCP child process environments
  • Manual complex dependencies — Docker and other heavyweight system dependencies are surfaced as manual setup requirements with setup links instead of being bundled into Row-Bot
  • No bundled MCP runtimes — Row-Bot depends on the Python MCP SDK, but external server runtimes are resolved at runtime so the app package does not ship Node, uv, Docker, or browser payloads unnecessarily
  • Private Cua boundary — Computer Use reuses managed-runtime and stdio primitives but its pinned driver, tool allowlist, disclosure, and exclusive service are Row-Bot-owned private integration state, not an installed external MCP server

Testing & Release Checks

  • Offline regression suite — tests/test_mcp_client.py covers config fallback, secret masking, safety classification, marketplace fallback/filtering, conflict policy, runtime requirement handling, managed environment injection, settings rows, stdio discovery/call, global disable, bad server failure, display names, background safety, and browser-loop handling
  • Opt-in live E2E — scripts/mcp_real_world_e2e.py and tests/test_mcp_real_world_e2e.py connect to public MCP servers outside normal CI to validate import, probe, manual tool enablement, dynamic wrapper invocation, and read-only approval classification
  • Maintainer workflow — MCP-heavy releases run the offline suite first, then the live public E2E check from the repo root

Migration Wizard

Row-Bot includes a one-time migration wizard for moving selected data from Hermes Agent or OpenClaw into a Row-Bot data directory without treating legacy state as trusted runtime configuration.

Flow & UI

  • Preferences launcher — ui/settings.py exposes Open Migration Wizard at the bottom of Settings → Preferences. The wizard opens in a maximized dialog so it stays available without occupying a permanent settings tab
  • Three-step flow — ui/migration_wizard.py guides users through source/target selection, read-only scan/review, and explicit apply
  • Provider support — users choose Hermes Agent or OpenClaw. Defaults point at ~/.hermes or ~/.openclaw, but any source and target folder can be selected for disposable test runs
  • Preview controls — categories and rows show status, selection state, conflict notes, manual-review notes, archive-only behavior, and report paths after apply

Detection & Planning

  • Pure migration package — migration/ owns the feature: core.py models plans/items/summaries, redaction.py masks secrets, detection.py scans sources read-only, planner.py builds dry-run plans, apply.py writes backups/reports, and fixtures.py creates realistic test homes
  • Read-only scan — detection and planning do not write to either source or target. Existing target files are only inspected to mark conflicts
  • Provider mismatch guard — Hermes scans reject OpenClaw-looking folders, and OpenClaw scans reject Hermes-looking folders, returning an empty actionable plan instead of partial generic matches
  • Mapped data — planners can map model/provider config, identity/persona files, long-term memories, OpenClaw daily memory, skills, MCP server definitions, and explicit API key/token entries
  • Risk boundaries — channel config, approvals, browser/cron/hooks/tools settings, legacy runtime state, logs, sessions, OAuth/auth stores, plugin state, and broad command allowlists are skipped for manual review or copied only into the migration report archive

Apply, Backups & Reports

  • Explicit apply — only selected planned/sensitive items are applied. Archive-only items are copied to the report archive, not activated in the live Row-Bot target
  • Backups first — existing target files are backed up before overwrite/append/update. Multiple writes to the same target preserve the pre-migration original once per run, and newly created files are not backed up later in the same run
  • Redacted report — each run writes redacted plan.json, result.json, backup_manifest.json, and summary.md under migration-reports/<timestamp>/
  • Archive redaction — JSON and key/value archive snapshots are redacted before being copied into reports; binary or unsupported files are represented by a placeholder instead of raw content
  • MCP import safety — migrated MCP servers are written disabled. They must be reviewed and enabled from Settings → MCP before any external tools become available to the agent
  • Credential import — API keys and tokens are off by default and require explicit selection. Reports hide their values; selected keys route through target-profile secure storage via api_keys.set_key_for_data_dir, so normal imports use the OS credential store with metadata-only local files when keyring is available

Testing

  • Focused suites — tests/test_migration_core.py, tests/test_migration_detection.py, tests/test_migration_planner.py, tests/test_migration_apply.py, and tests/test_migration_wizard_ui.py cover model invariants, source detection, dry-run planning, wrong-provider rejection, conflict behavior, backups, reports, redaction, daily memory import, and UI helper logic
  • Realistic fixtures — migration/fixtures.py builds multi-month Hermes and OpenClaw homes with fake secrets, memories, skills, channels, MCP servers, approvals, cron/hooks, plugins, sessions, logs, and archive-only state
  • Manual E2E path — disposable targets under .tmp/migration-fixtures/ are used for click-through validation during migration testing; the fixture root is ignored by git

Legacy Thoth Upgrade Policy

Current Row-Bot releases no longer run the old automatic Thoth-to-Row-Bot rebrand migration during startup. That migration shipped for multiple Row-Bot releases after the v4 rename and has been removed from the hot startup path.

  • Supported path - users who are still on Thoth or an early Row-Bot build must first install and launch a previous migration-capable Row-Bot release, then upgrade to the current release.
  • Startup posture - current startup reads Row-Bot data from ROW_BOT_DATA_DIR or the default .row-bot directory and does not scan, copy, repair, or rewrite .thoth data.
  • Legacy plugin posture - plugin loading can still quarantine old Thoth plugin manifests or code so stale plugins do not break startup.
  • Current migration wizard - the Preferences migration wizard remains focused on Hermes/OpenClaw archives and is separate from the removed rebrand bridge.

Plugin System & Marketplace

A sandboxed, hot-reloadable extension system lets plugins add native tools, plugin-packaged MCP-backed tools, bundled skills, and channels without modifying the core codebase.

Plugin Architecture

  • Plugin API — PluginAPI, PluginTool, and public channel base exports are the abstractions available to plugins through plugins.api
  • Manifest system — each plugin declares v2 metadata, supported surfaces (native_tools, mcp_servers, channels, and skills), settings, secrets, auth, permissions, and health checks in plugin.json
  • Security sandbox — AST scans block dangerous constructs like eval, exec, subprocess, shell escape paths, UI frameworks, and imports from Row-Bot internals
  • Dependency safety — v2 plugins do not install Python dependencies into Row-Bot's runtime environment; plugin-packaged MCP servers provide an external process boundary when needed
  • State persistence — enablement and non-secret config are stored under ~/.row-bot/plugin_state.json; plugin API-key secrets use the OS credential store with metadata-only plugin_secrets.json state and session-only fallback for new saves when keyring is unavailable
  • Hot reload — Settings can reload plugins without restarting the app; agent caches are cleared automatically
  • Skill auto-discovery — plugin skills/ directories are scanned for SKILL.md definitions and injected only while the owning plugin is enabled and selected by the active Agent Profile tool boundary

Marketplace

  • Marketplace index — v2 plugin catalog fetched from GitHub-hosted JSON or a local fixture index, with caching, stale-cache fallback, checksums, source metadata, and update checks
  • Browse dialog — search, inspect, review permissions, and install plugins from within the app
  • Install / update / uninstall — plugins are validated before install, installed and kept off by default, checksum-verified when catalog data provides a sha256: value, and reloaded immediately afterward
  • Native Plugin Center — one Row-Bot-owned UI renders per-plugin metadata, permissions, settings, secrets, auth, health checks, tools, channels, skills, logs, updates, and enable/disable controls; plugin-owned channels do not render arbitrary custom UI
  • Custom Tool bridge — promoted Custom Tools are registered through the plugin/tool surface as synthetic local tools so normal chat can use them without adding a separate extension mechanism
  • Public channel API — channel plugins receive public inbound/outbound dataclasses, attachment helpers, approval resume helpers, pairing/allowlist helpers, and generated webhook URLs through plugins.api
  • Plugin webhooks — plugins/webhooks.py registers namespaced webhook routes under /plugin-webhooks/{plugin_id}/{name} and disables them when the owning plugin is disabled, unloaded, uninstalled, or fails load
  • Bot Framework auth — plugins/bot_framework_auth.py validates Bot Framework JWTs with OpenID/JWKS discovery, issuer/audience checks, and display-safe error reporting for channel plugins

Auto-Updates

updater.py polls the GitHub Releases API for the official Row-Bot repo on a background thread (30-second startup delay, then every 6 hours, with a 24-hour debounce on actual network calls). Checking is on by default; if there is no internet the call fails silently and the next tick retries.

  • Channel — stable (default) hits /releases/latest; beta walks the top 10 releases and includes pre-releases. Persisted in ~/.row-bot/update_config.json.
  • Manifest verification — every release body must contain a fenced <!-- row-bot-update-manifest --> block with SHA256 hashes for each platform asset. Without a manifest entry, download_update refuses to install. The CI workflow .github/workflows/update-manifest.yml calls scripts/append_sha_manifest.py to PATCH the release body once artifacts are uploaded. The Linux one-line installer uses the same manifest before running the bundled tarball installer.
  • OS code signature — Windows installs invoke signtool.exe verify /pa; macOS installs invoke codesign --verify --deep --strict. Linux tarball installs do not have a universal OS-level signing verifier, so Row-Bot relies on GitHub HTTPS plus the required SHA256 release manifest.
  • Hand-off — Windows: a detached update_handoff.py helper asks the running app to quit, waits for known Row-Bot PIDs and the local port to clear, then starts Row-Bot-x.y.z-Windows-x64.exe /SILENT /CLOSEAPPLICATIONS /RESTARTAPPLICATIONS. The .iss uses CloseApplications=yes / RestartApplications=yes so Inno Setup can swap files safely, and repair/upgrade deletes {app}\python before recopying the bundled runtime so stray packages installed into embedded Python cannot survive. macOS: open <dmg> and exit; the user drags the new app to /Applications. Linux: install the verified Row-Bot-X.Y.Z-Linux-ARCH.tar.gz into the user XDG release tree, atomically flip ~/.local/share/row-bot/current, refresh the desktop entry/icon, and restart through ~/.local/bin/row-bot.
  • UI — a green "⬆ vX.Y.Z" status-bar pill appears when a newer release is detected; clicking opens the What's-New dialog (rendered release notes plus Install / Skip / Later buttons). Settings → Preferences → Updates exposes channel selection, "Check for updates", and a list of skipped versions.
  • Agent surface — tools/updater_tool.py registers row_bot_check_for_updates (read-only) and row_bot_install_update (interrupt-gated). The dynamic self-knowledge block surfaces "Update available: …" when applicable, and row_bot_status adds an updates category.
  • Dev installs — when a .git/ directory sits next to the app source (i.e. running from a checkout), the scheduler is disabled and row_bot_install_update refuses, so working copies are never overwritten. On Linux, packaged installs are recognized by install_info.json with platform: linux and install_kind: xdg-user-tarball.

Habit & Health Tracker

  • Conversational tracking — log medications, symptoms, exercise, mood, sleep, periods, and other recurring data in natural language
  • Auto-detect & confirm — the agent recognizes likely trackable events and asks before writing anything
  • 3 tracker operations — structured logging, flexible querying, and destructive delete with confirmation
  • Built-in analysis — adherence, streaks, numeric summaries, frequency, day-of-week patterns, cycle estimation, and co-occurrence analysis
  • Trend visualization — tracker queries can export CSV and chain directly into the chart tool for Plotly output
  • Fully local — tracker data lives in ~/.row-bot/tracker/tracker.db
  • Memory isolation — tracker entries are intentionally excluded from the personal knowledge graph

Desktop App

  • Native window — runs in a desktop window via pywebview on Windows and macOS; Linux defaults to browser mode and can opt into --native when the desktop has the required GTK/Qt backend
  • System tray — launcher.py exposes open and quit controls plus running-state feedback on Windows and macOS; Linux defaults to no tray and can opt into --tray when AppIndicator/desktop support is available
  • Native macOS tray host — packaged macOS builds include installer/macos/RowBotTrayHost.m, a small native status-item host that keeps tray content visible and avoids fragile cross-platform tray fallbacks
  • Splash screen — Tk-based loading splash during startup; Tk failures are logged to launcher diagnostics, and the visible console fallback is opt-in for debugging instead of appearing during normal Windows launches
  • Startup diagnostics — startup_diagnostics.py runs early in app.py and probes fragile optional native packages. Missing optional packages are ignored; installed-but-broken packages such as TorchCodec are logged with recovery steps and patched out of optional Transformers availability checks where safe.
  • First-launch setup wizard — starts with model/provider choice, then migration and setup-center steps for Local, Providers, Custom/Self-hosted, memory/docs, workflows, Agent/Profile surfaces, Designer, Developer, channels, voice, and related setup without touching config files by hand
  • Self-contained installers — Windows and macOS releases bundle dependencies for one-click setup; Linux uses a one-line bootstrapper that verifies and installs the self-contained XDG tarball into user-owned paths
  • Packaged runtime validation — Windows packaging validates embedded Python, bundled Tk, required native DLLs, and startup smoke paths so splash/picker failures are caught before artifact publication
  • Launcher identity and ports — the launcher probes /api/launcher-ping before reusing port 8080, passes the chosen port through ROW_BOT_PORT, and supports explicit --browser, --native, --tray, --no-tray, --server, --no-open, --port, and --host modes
  • First-run window picker — launcher-managed native/browser mode selection prefers the Tk picker and fails quickly to a safe default if the helper cannot render, avoiding hidden or blank console prompts on packaged Windows
  • Launcher recovery hints — when the managed server exits during startup, launcher.py tails ~/.row-bot/row_bot_app.log and emits targeted recovery hints for recognized startup signatures, including broken optional TorchCodec DLL loads in the embedded Windows runtime.
  • Launcher data recovery commands — launcher.py --reset-tasks-db, --reset-db, and --restore-data back up SQLite DB families before recreating or restoring known task, memory, and thread databases
  • Docs capture mode — app-side docs capture hooks expose stable, seeded UI states to local documentation automation without affecting normal runtime startup
  • Computer Use setup — the System tab keeps browser and native-app automation separate, requires the Cua telemetry acknowledgement before executable use, installs the pinned runtime only on demand, and guides macOS Accessibility/Screen Recording recovery
  • Auto-restart flow — closing the native window does not kill the tray-managed app process; reopen is fast
  • Release pipeline — build, sign, notarize, and publish automation lives in CI

Mobile Web Companion

The mobile companion is a browser-first client served by the same local Row-Bot process. It does not introduce a Row-Bot account, cloud relay, or separate sync backend: paired phones read and mutate the same local threads, workflows, knowledge, provider metadata, skills, plugins, and approval state as desktop.

Mobile Shell

  • Explicit client routing — ui/mobile.py selects the mobile shell for ?mobile=1 requests and authenticated remote mobile cookies; desktop loopback clients keep the desktop shell unless mobile mode is requested explicitly
  • Phone-native navigation — Chat, Activity, Workflows, Knowledge, and Settings render as full-height mobile surfaces without desktop drawers, terminal, Buddy, Developer Studio, or Designer Studio chrome
  • Shared durable state — mobile chat uses the normal thread/checkpoint store, agent streaming path, file attachments, profile/model selection, manual skills, auto-title rules, and generation controls
  • Activity surface — tool approvals, workflow approvals, active chat generations, running/stoppable workflows, and recent workflow history are combined into a compact operational view
  • Safe workflow editing — the simple mobile editor can create and update prompt workflows while detecting and preserving advanced graph workflows that require desktop controls
  • Settings adapters — provider cards expose display-safe connection and credential summaries; installed skills can be enabled or pinned; installed plugins can be enabled or disabled when setup is complete; Skills Hub and Plugin Marketplace install/configure/update flows remain desktop-only
  • PWA boundary — mobile/routes.py serves the manifest, service worker, icon metadata, and offline page; the service worker caches only public shell assets and explicitly avoids authenticated/private application routes

Pairing & Access Control

  • Route discovery — mobile/access_info.py combines the active bind host/port, local-network candidates, optional Tailscale direct/Serve state, an existing ngrok URL, and advanced custom origins into display-safe pairing choices
  • Short-lived pairing — the desktop or an already paired settings-scoped device creates an expiring, single-use ticket; the QR/link carries only the pairing code and the confirmed long-lived token is returned only in an HttpOnly cookie
  • Hashed secrets at rest — mobile/store.py stores salted hashes for pairing secrets and device tokens in mobile.db, plus device display metadata, scopes, revocation timestamps, failed-attempt counts, and display-safe access events
  • Scheme-aware cookies — HTTPS uses a Secure host-prefixed cookie; LAN HTTP uses a separate HttpOnly cookie name without pretending the transport is secure; both use SameSite protection and keep tokens out of response bodies and URLs
  • ASGI gate — mobile/access_gate.py guards both HTTP and WebSocket scopes before NiceGUI handling. Direct loopback without forwarding headers remains trusted for the desktop, while remote or forwarded requests require a valid non-revoked device token except for the minimal pairing/session/PWA routes
  • Forwarded-header defense — Forwarded, X-Forwarded-*, CDN/client-IP, and related headers prevent a proxy request from claiming the loopback exemption
  • Device revocation and audit — authorized settings sessions can list devices, revoke them immediately, and inspect recent paired/failed/revoked/session events without exposing stored token material
  • Private-route preference — Mobile Access recommends Tailscale Serve/direct or LAN before a public tunnel; ngrok and custom public URLs remain pairing-gated but are accompanied by explicit exposure warnings

Mobile Limitations

  • Host required — the desktop/server process must remain running and reachable; mobile is not an offline replica even though the PWA provides an offline status page
  • Desktop-owned studios and marketplaces — Developer Studio, Designer Studio, Skills Hub browsing/install/create, Plugin Marketplace setup/update/uninstall, and advanced workflow graph editing stay on desktop in Mobile V1
  • No native Computer Use — mobile, channel, scheduled, workflow, child-agent, and headless/server turns cannot acquire the native desktop-control lease; Computer Use is restricted to the interactive local desktop UI
  • No hidden network enablement — Row-Bot does not automatically change its bind host or install/configure Tailscale. Direct LAN/Tailscale access beyond loopback requires an explicit host choice; Tailscale Serve or an existing tunnel can proxy to loopback

Chat & Conversations

  • Multi-turn threads — conversation history is stored in SQLite via LangGraph checkpointing and local thread metadata
  • Auto-naming and switching — threads are named from the conversation and can be reopened, exported, or deleted individually; placeholder mobile titles remain auto-renamable while manual names retain ownership and are never overwritten by a later first message
  • Per-thread model override — conversations can pin a different local or provider model than the global default
  • Per-thread Agent Profile — conversations can carry a selected Agent Profile whose instructions and policy are injected into agent and chat-only turns
  • Goal Mode continuity — active goals, progress, blockers, and continuation decisions are tied to the thread so long work stays visible across turns
  • Input-level model picker — the main chat model selector lives in the chat input area, loads cached options immediately, refreshes asynchronously, and keeps the top bar focused on thread state
  • File attachments — drag-and-drop, clipboard paste, and standard upload flows handle images, PDFs, spreadsheets, JSON, and text
  • Media persistence — chat media is stored per thread on disk with sidecar metadata; generated content persists more aggressively than transient capture artifacts
  • Inline rich rendering — Plotly charts, Mermaid diagrams, YouTube embeds, syntax-highlighted code, and images render directly in the transcript
  • Shared chat components — ui/chat_components.py provides the input bar, upload flow, and message container for main chat, Designer Studio, and Developer Studio
  • Bounded transcript rendering — ui/transcript.py chooses a visible window for large threads, exposes load-earlier behavior, and avoids rendering every historic row on initial open
  • Checkpoint loading without graph import — transcript loaders can read checkpoint messages and token usage without constructing the agent graph, reducing blank-thread and large-thread latency
  • Status monitor panel — Home health-check pills, diagnosis actions, and quick settings links surface runtime health at a glance
  • Workflow Console integration — approvals, active goals, child-agent runs, recent workflow runs, and insight actions are visible without leaving the conversation experience
  • Agent drawer and profile UI — child-agent status, profile selection, Profile Library, and run activity are exposed through dedicated UI surfaces instead of being hidden in transcript text
  • Child-agent approval messages — approval requests and async completion summaries are inserted at the correct parent-turn boundary, deduplicated across live rendering and reload, and carry UI metadata through LangChain checkpoint conversion
  • Streaming hardening — detached streams persist final content and media, grouped tool-call counts update during streaming, thinking text survives reattach/final render, and safe timer helpers avoid UI writes after clients disconnect
  • Live control cards — browser and Computer Use runs surface a shared sanitized control card with direct Stop/takeover/resume state, while native screenshots remain ephemeral and shielded during user or approval handoff
  • Active-thread feedback — the sidebar spinner is bound to genuinely streaming state for the active thread and remains independent of pinned/recent ordering
  • Output truncation warnings — the UI warns when a response was cut short by model token limits

Notifications

  • Desktop notifications — workflow completions, reminders, and other events can raise OS-level notifications
  • Sound effects — distinct audio chimes are used for workflow completion and timer-like alerts
  • In-app toasts — lightweight status notifications appear in the UI; errors can remain persistent until dismissed
  • Unified API — all notification surfaces flow through a single notify() entry point
  • Approval awareness — approval requests can surface as both UI notices and channel-delivered prompts
  • Durable terminal notices — child-agent and Goal Mode terminal events can be persisted for once-only channel delivery, retried after channel startup, and recorded in the conversation checkpoint after successful send

Stability & Diagnostics

Row-Bot includes a stability layer for the kinds of failures that are hard to catch from normal request logs: UI callback crashes, client-side JavaScript errors, event-loop stalls, memory spikes, and startup/shutdown issues.

  • stability.py — centralizes crash reporting, UI callback error reports, client-side error capture, asyncio exception handling, thread/unraisable hooks, memory snapshots, and event-loop lag logging
  • Launcher diagnostics — launcher.py writes structured launch timing, splash/picker helper failures, server readiness, window-open decisions, and shutdown/update handoff events to launcher.log
  • Safe timers — ui/timer_utils.py wraps deferred UI callbacks and polling timers so disconnected clients or deleted NiceGUI slots do not crash the app silently
  • Settings diagnostics — model settings collection/render phases log timings and memory snapshots, while cached model catalogs and short-lived provider-status caches keep large provider refreshes and OAuth health checks off the critical UI path
  • UI performance helpers — ui/performance.py provides render generation tokens, timed UI sections, slow-section logging, and safe UI callback/task wrappers used by Settings, Knowledge, chat, and graph surfaces
  • Startup sequencing — startup status covers cached model catalog load, workflow scheduler, stale Agent Run recovery, MCP, plugins, channel migration/autostart, tunnel startup, and knowledge graph load
  • Clean shutdown — app shutdown attempts ordered channel, tunnel, MCP, scheduler, and process cleanup to reduce locked logs and lingering child processes
  • Cancellation diagnostics — provider response closure, subprocess termination, cancelled MCP futures, channel preview cleanup, and generation-linked child-stop behavior emit scoped diagnostics rather than being misreported as successful completion
  • Computer Use diagnostics — readiness codes, pinned-runtime verification, permission recovery, private-client shutdown, target invalidation, and lease cleanup are logged without typed values, screenshot bytes, or raw action arguments
  • Task database diagnostics — Home, Command Center, and Row-Bot Status can report workflow/agent/goal schema state, repair results, and launcher recovery guidance when workflow storage is missing or corrupt
  • Frontend error reporting — browser-side exceptions are reported back into the structured log with enough context to correlate with UI actions
  • Performance probes — memory RSS/VMS/thread counts, event-loop lag, token-counter refresh, model settings load, Settings tab render generations, transcript rendering, FAISS rebuild, and catalog refresh timings are logged for support investigations

Bundled Skills

Skills are reusable instruction packs that shape how the agent thinks and responds. Each skill is a SKILL.md file with YAML frontmatter (display name, icon, description, required tools, tags) and freeform instructions injected into the system prompt when enabled.

Row-Bot ships with 17 manual bundled skills and 22 tool guides. Manual skills are toggled from Settings; tool guides auto-activate when their linked tools are available.

SkillDescription
🧠 Brain DumpCapture unstructured thoughts and organize them into structured notes saved to memory
💻 Claude Code DelegationCoordinate Claude Code CLI as an external coding agent through Row-Bot's approval-gated shell workflow
☀️ Daily BriefingCompile a morning briefing with weather, calendar, and news headlines
📊 Data AnalystAnalyze datasets, produce statistical summaries, and create insightful charts
💻 Developer CodingPlan and implement scoped code changes in Developer Studio using repo-aware tools and approval policy
🔎 Developer ReviewReview code for bugs, regressions, missing tests, and risky behavior before summarizing
🚀 Developer PR PrepPrepare branch, test, commit, push, and PR-ready summaries for Developer workspaces
🧩 Developer Custom ToolsDesign, test, and promote Custom Tools from repos or folders without over-broad command surfaces
🔬 Deep ResearchPerform multi-source research on a topic and produce a structured report
🎨 Design CreatorStructured workflow for presentations, one-pagers, reports, and visual layouts in Designer Studio
🗣️ HumanizerWrite in a natural, human tone without AI-speak or corporate filler
📚 Knowledge BaseManage the personal knowledge base across graph memories, document intelligence, and the wiki vault
📋 Meeting NotesTurn raw notes into actionable minutes with follow-ups and clear structure
🎯 Proactive AgentAnticipate user needs, ask clarifying questions, and self-check work at milestones
🪞 Self-ReflectionReview memory for contradictions, gaps, and stale information
⚙️ Task AutomationDesign effective workflows with steps, conditions, approvals, triggers, and delivery routing
🌐 Web NavigatorStrategic patterns for browser automation, research, forms, and data extraction
  • Claude Code Delegation — disabled by default, this skill treats Claude Code CLI as an external coding worker while Row-Bot remains coordinator. It favors bounded claude -p print-mode tasks, explicit working-directory checks, --allowedTools, turn/budget limits, diff inspection, Row-Bot-side verification, and user approval before write-capable or destructive delegation.
  • User skills — custom skills live in ~/.row-bot/skills/<name>/SKILL.md; user skills with the same name as a bundled skill override it
  • In-app skill editor — skills can be created and edited directly from Settings
  • Skills Hub install path — Skills Hub installs third-party or user-provided skills into the same user skill library, preserving provenance while keeping bundled skills immutable
  • Per-skill enablement — only enabled manual skills are injected into the system prompt
  • Pinned defaults — users and status-tool actions can pin selected skills as default active guidance, while explicit composer/thread/workflow selections still narrow the prompt for a specific context
  • Per-thread, per-workflow, and composer overrides — skill selection can be narrowed for individual threads and workflows, while chat composer controls expose explicit skill chips and slash-command activation
  • Tool guides remain automatic — Agents, Browser, Calendar, Chart, Custom Tool Builder, Designer, Developer, Email, Filesystem, Goal, Math, MCP, Shell, Telegram, Row-Bot Status, Tracker, Updater, Video, Vision, Weather, Wiki, and X guides are in the built-in set

Public Docs Site & Automation

The hand-curated public landing page under docs/ remains separate from the generated public documentation site. Docusaurus source lives under docs-site/; the reviewed static build is synchronized into selected generated directories under docs/ and is published through GitHub Pages when the source and artifact merge to main.

  • Docusaurus source — docs-site/ contains the documentation application, sidebars, authored/generated MDX, Pagefind integration, brand/static assets, and local preview/build scripts
  • Comprehensive guide structure — source pages cover getting started, app shell, chat, profiles/goals/agents, workflows, Designer and Developer Studios, integrations, settings, knowledge/wiki/provenance, operations, extension trust, mobile/native behavior, privacy, troubleshooting, concepts, and generated references
  • Structured coverage map — docs-content/metadata/ui_surfaces.yml is the authoritative user-facing surface inventory; routes, screenshots or no-image reasons, settings/home/dialog inventories, and how-to metadata feed generation and validation
  • Isolated real UI capture — docs_capture.py, seed_real_app_demo_data.py, and capture_real_ui_screenshots.py refuse the normal data directory, disable background autostart/network status checks, seed neutral display-only provider/channel/plugin/MCP states, and capture stable desktop/mobile scenarios
  • Screenshot review contract — capture metadata records stable ids, scenarios, viewport, status, and source route; reviewers check every changed image for private data, misleading state, clipping, and legibility before marking it approved
  • Generation scripts — collect_inventory.py, generate_mdx.py, write_public_user_guide_pages.py, generate_llms_txt.py, and templates turn source/runtime inventories into control-level references, human pages, and machine-readable llms.txt / llms-full.txt
  • Searchable static output — the Node build runs Pagefind over Docusaurus output and commits the resulting HTML, assets, screenshot copies, search index, sitemap, and machine-readable files under the generated docs/ paths used by Pages
  • Deterministic publication sync — sync_github_pages.py refreshes only docs/assets, docs/docs, docs/img, docs/pagefind, docs/search, and selected machine-readable files; it preserves docs/index.html, feature/contact/architecture pages, analytics, contact handling, and shared marketing assets
  • CI verification — .github/workflows/docs.yml collects inventory, checks generated references, regenerates LLM files, validates screenshots and source, builds a review report, runs tests/docs, builds Docusaurus and Pagefind, and verifies the committed Pages artifact structurally
  • Review posture — documentation generation and publication remain source-controlled and reviewable, do not call live providers/channels/MCP servers during deterministic CI, and remain distinct from installer/release artifact generation

Core Modules

Runtime code is packaged under src/row_bot. The paths below are package-relative unless a top-level docs, scripts, installer, or static directory is named explicitly.

FilePurpose
app.py + ui/NiceGUI application shell, desktop and mobile routing, chat surfaces, lazy home tabs, health/status bar, workflow console, Agent drawer, Goal UI, Profile Library, Computer Use setup/live-control surfaces, settings dialog, docs capture hooks, UI performance helpers, and native-webview integration points
mobile/ + ui/mobile*.pyMobile pairing/auth store, cookies, access gate, route and Tailscale/LAN/tunnel discovery, PWA endpoints, full-screen shell, chat, Activity, workflow editor, Mobile Access settings, and phone-safe provider/skill/plugin settings
brand.py + runtime_paths.pyRow-Bot product identity, public naming constants, runtime path detection, and packaged/source checkout path helpers
buddy/ + ui/buddy.pyBuddy companion event bus, behavior brain, config, asset validation, Hatch generation, in-app docked/undocked presence, and optional desktop overlay helpers
designer/Designer Studio subsystem: gallery, editor, tooling, storage, exports, presentation mode, publishing, and asset hydration
developer/Developer Studio subsystem: workspace links, Git helpers, durable worktree allocation, approval policy, Docker/local runtime, sandbox state, inspector snapshots, todos, file tree, diffs, GitHub helpers, Custom Tool internals, and UI
ui/chat_components.pyShared chat input, upload, and message-area components reused by main chat, Designer Studio, and Developer Studio
ui/chat_composer_extras.pyShared slash palette, skill picker, skill chips, and composer-level Smart Skills controls reused across chat surfaces
agent.pyLangGraph ReAct agent, prompt assembly, Agent Profile injection, tool allowlist handling, checkpointed budget hooks/finalization, runtime readiness routing, chat-only execution, provider transcript normalization, streaming event generation, tool routing, interrupt handling, cache clearing, and background execution integration
agent_budget.py + agent_settings.pyCheckpoint-safe model-iteration budgets, no-progress digests, exactly-once terminal finalization, validated application-wide work/delegation limits, and atomic agent_settings.json persistence
agent_profiles.py + agent_context.py + agent_tool_catalog.pyBuilt-in/user Agent Profile registry, profile persistence, profile context assembly, policy blocks, profile search/selection helpers, and tool catalog metadata for scoped delegation
agent_runner.py + agent_runs.py + agent_run_messages.pyDurable Agent Run FIFO/capacity queue, child-agent nesting/active-time lifecycle, settings snapshots and model-iteration progress, parent-thread lifecycle/approval/completion messages, run events, parent/child edges, generation-linked stop/wait/resume state, write locks, stale-run recovery, and shared Agent Run tables in tasks.db
approval_messages.pyNormalized approval payloads, model-reason preference, redaction/truncation, compact channel/mobile rendering, and display-safe source labels
cancellation.py + process_cancellation.pyGeneration-scoped cleanup registration, provider/tool/browser/Computer Use/process Stop propagation, process-group termination, timeout handling, and cancellation results
goals.pyThread-scoped Goal Mode state, goal commands, progress/evidence/blocker tracking, continuation prompts, verifier decisions, and synchronization with Agent Run status
approval_policy.py + tools/approval_gate.pyUnified approval modes and tool-level approval gate helpers for chat, Developer, workflows, channels, and promoted tools
threads.pySQLite-backed thread metadata, LangGraph checkpoint wiring, checkpoint transcript helpers, per-thread media storage, thread-level model/profile overrides, and cleanup hooks for chat-created agent/goal run state
memory.pyBackward-compatible memory wrapper that maps legacy memory calls onto the knowledge graph implementation
memory_policy.py + memory_evolution.pyBounded auto-recall scoring/filtering/tracing plus memory status, tier, confidence, evidence, review, superseding, archival, and evolution journal helpers
knowledge_graph.pyEntity/relation store, FAISS and FTS5 recall, NetworkX traversal, deduplication, relation normalization, recall reinforcement, and graph stats
wiki_vault.pyObsidian-compatible markdown vault export, indexing, search, and conversation export
dream_cycle.pyNightly graph refinement engine: merges, enrichment, decay, relation inference, insights analysis, proposal seeding, and journal logging
evolution.pyControlled self-evolution proposal store, validation, action runs, rejection memory, feedback reports, skill mutation bounds, and curator dry-runs
document_extraction.pyBackground document map-reduce extraction pipeline with provenance-aware graph writes
models.pyLocal model compatibility facades, context policy, context caps, Quick Choices, provider detection, xAI OAuth catalog bridge, model factories, and legacy model APIs
prompt_context.py + prompt_cache.pyPrompt section assembly, stable/ephemeral section inventory, direct-Anthropic prompt-cache marker gating, stable fingerprint reporting, and provider cache usage normalization
providers/Provider auth, normalized model catalogs, provider-isolated last-known-good catalog refresh, capability resolution, Gemini tool-schema compatibility, Atlas Cloud, Requesty, Claude Subscription, xAI Grok OAuth, xAI media/catalog helpers, provider-qualified resolution, readiness evaluation, custom endpoint profiles/probes, cancellable runtime construction/transports, and display-safe provider status
embedding_config.py + embedding_providers.pyEmbedding provider selection, strict cache-only local loading, explicit download/repair, shared asynchronous provider state, structured recall fallback, local/cloud backends, vector metadata, and stale-index detection
documents.pyDocument ingestion, chunking, embedding, vector-store persistence, and per-document cleanup
voice.pyClassic faster-whisper-based speech input pipeline and voice-state management
voice/Realtime voice runtime, provider contracts, OpenAI realtime client, local-provider scaffolding, action dispatch, agent bridge, cue policy, speech policy, and output coordination
tts.pyKokoro text-to-speech integration, voice catalog, and streaming playback
vision.pyCamera capture, screen capture, and workspace image analysis via local or provider vision models
computer_use/ + tools/computer_use_tool.py + ui/computer_use.py + ui/live_control.pyPinned Cua manifest/private client, disclosure/install/readiness, action policy, exclusive target-window service, native application tool, macOS permission recovery, and ephemeral live-control UI
data_reader.pyShared structured-data loader for CSV, TSV, Excel, JSON, and JSONL
data_paths.pyShared Row-Bot data-directory and SQLite path resolution for tasks, memory, threads, diagnostics, and recovery commands
docs_capture.pyApp-side helpers for seeded real UI documentation capture and screenshot automation
launcher.pyDesktop launcher, native/tray selection, splash screen, first-run window picker, app lifecycle, logging bootstrap, local runtime startup decisions, macOS native tray host integration, and DB recovery commands
update_handoff.pyDetached Windows update handoff helper that waits for Row-Bot processes/ports to exit before starting the installer
stability.pyUI callback/error capture, asyncio/thread exception hooks, memory snapshots, event-loop lag logging, and crash diagnostics
startup_diagnostics.pyEarly startup probes for optional native packages that can break app import/startup when partially installed
api_keys.py + secret_store.pyAPI key storage and retrieval for tools and API-key providers, backed by OS keyring with metadata-only local files, legacy plaintext migration, and session-only fallback when secure storage is unavailable
identity.pyAssistant name, personality, and self-improvement preference storage with sanitization
self_knowledge.pyCapability manifest, identity-line builder, live runtime state builder, and prompt-time self-knowledge assembly
insights.pyStructured insight store with dedup, pruning, pin/dismiss/apply state, and last-analysis tracking
prompts.pyCentralized prompt templates including summarization, extraction, and dream-insights analysis
memory_extraction.pyBackground conversation scan that extracts entities and relations the live agent did not save
skills.pyDiscovery, loading, enablement state, pinned defaults, override, and prompt-building for manual skills and tool guides
skills_activation.py + slash_commands.pySmart Skills activation, pinned/manual defaults, explicit skill commands, draft suggestions, disabled-skill handling, and slash-command parsing
skills_hub/Skills Hub source adapters, import detection, installers, provenance, scanner, search index, source registry, and UI models
bundled_skills/17 built-in manual skills as SKILL.md packages
tool_guides/22 built-in tool-specific auto-activation guides
tasks.pyWorkflow engine, SQLite persistence, schema validation/repair, APScheduler scheduling, profile-first workflow migration, pipeline execution, run history, safety mode, delivery routing, and shared storage connection used by Agent Profiles/Runs/Goals/Developer worktrees
notifications.pyUnified desktop, sound, and toast notification system
channels/Channel ABC, registry, shared streaming/finalization engine, durable thread notifications, checkpoint persistence, media helpers, auth helpers, approval routing, command handling, tool generation, plugin-channel bridge integration, and bundled channel adapters
tunnel.pyTunnel provider abstraction, ngrok integration, and lifecycle manager
tools/agent_tool.py + tools/goal_tool.pyChild-agent delegation/status/wait/stop/profile/promotion tools plus Goal Mode progress/status tools
tools/row_bot_status_tool.pySelf-introspection and controlled self-management tool, including provider/media diagnostics, agent/goal reporting, skill pinning, and controlled self-evolution proposal operations
tools/developer_tool.py + tools/custom_tool_builder_tool.pyDeveloper workspace operations plus hardened conversational Custom Tool creation/testing/promotion surface
tools/calendar_tool.pyRequest-scoped Google Calendar services, single-flight OAuth refresh, serialized mutations, bulk create, transient retry, timeout reconciliation, and typed Calendar operations
tools/ + designer/tool.pySelf-registering core tool modules, registry, base classes, Wikipedia recovery behavior, and LangChain tool conversion
plugins/Plugin System v2 runtime, marketplace client, manifest validation, security scanner, Plugin Center UI, public API, channel runtime bridge, webhooks, Bot Framework auth helpers, MCP bridge, devtools, templates, and settings integration
mcp_client/External Model Context Protocol client plus shared managed-runtime primitives: config, runtime sessions, marketplace search, requirements, safety classification, diagnostics, and result normalization; private Cua transport remains outside the external MCP registry
migration/Hermes/OpenClaw migration models, redaction, source detection, dry-run planning, realistic fixtures, guarded apply/report generation, and migration tests
docs-site/ + docs-content/ + scripts/docs/Public docs source, coverage metadata, generated MDX/control references, isolated real UI screenshot capture, validation/review, LLM text generation, Pagefind search build, and deterministic GitHub Pages synchronization
static/Bundled frontend assets such as Mermaid, graph/visualization helpers, and Buddy runtime/motion assets
version.pySingle source of truth for the current Row-Bot version, located at src/row_bot/version.py

Data Storage

All user data is stored under ~/.row-bot/ (or %USERPROFILE%\\.row-bot\\ on Windows) unless ROW_BOT_DATA_DIR is set.

~/.row-bot/
├── threads.db                     # Conversation history and LangGraph checkpoints
├── media/                         # Per-thread media files and sidecar metadata
├── tasks.db                       # Workflows, schedules, Agent Profiles, Agent Runs, thread goals, Developer worktree ownership, write locks, run history, approvals, and durable channel notification intents
├── memory.db                      # Knowledge graph entities and relations
├── memory_vectors/                # FAISS vectors for semantic memory recall
├── memory_recall_trace.json       # Recent auto-recall decisions, semantic fallback/timing, and include/reject diagnostics
├── memory_evolution_journal.json  # Memory status/tier/review/superseding/audit changes
├── memory_extraction_state.json   # Last extraction metadata
├── extraction_journal.json        # Memory extraction journal
├── dream_config.json              # Dream Cycle settings
├── dream_journal.json             # Dream Cycle run log
├── dream_rejections.json          # Rejected inference-pair cache
├── insights.json                  # Structured insight store
├── controlled_evolution.json      # Controlled self-evolution proposals, action runs, rejection memory, and curator reports
├── feedback_reports/              # Redacted local feedback reports generated from controlled proposals
├── evolution_backups/             # Rollback references for controlled skill patch proposals
├── api_keys.json                  # API key metadata only; raw key values live in the OS credential store when available
├── cloud_config.json              # Legacy provider-model pinning compatibility data
├── providers.json                 # Provider metadata, Quick Choices, compatibility profiles, runtime/vision probe results, OAuth client-id diagnostics, model-count status, and credential fingerprints only
├── model_settings.json            # Current model, context caps, and model setting compatibility state
├── model_catalog_cache.json        # Background-refreshed provider/local-runtime model catalog rows and refresh diagnostics
├── context_catalog_cache.json      # Cached context-window metadata used before live provider refresh
├── embedding_config.json           # Active embedding provider/model settings
├── agent_settings.json             # Application-wide work rounds, child nesting/concurrency, and optional active-time limit
├── computer_use_settings.json      # Cua disclosure version, verified readiness state, and optional reviewed system-binary metadata
├── app_config.json                # Onboarding and first-run flags
├── user_config.json               # Avatar preferences, identity, and self-improvement settings
├── channels_config.json           # Channel enablement and per-channel config
├── mobile.db                      # Hashed mobile pairing/device credentials, scopes, revocation state, and display-safe access events
├── developer/
│   ├── workspaces.json             # Developer workspace links, approval mode, execution mode, sandbox image/network settings
│   ├── tool_capsules.json          # Registered Custom Tools and promotion/enablement metadata
│   ├── custom_tool_drafts.json     # Conversational Custom Tool Builder draft state
│   └── sandboxes/                  # Docker shadow workspaces and per-workspace sandbox state
├── shell_history.json             # Per-thread shell history
├── skills_config.json             # Manual skill enable/disable state
├── skills/                        # User-installed skills; .hub/ stores Skills Hub lockfile, audit log, and quarantine
├── mcp_servers.json               # External MCP server config, global switch, tool enablement, approvals
├── mcp_marketplace_cache.json     # Cached MCP directory search results
├── migration-reports/             # Redacted migration plans, results, summaries, and archive snapshots
├── migration-backups/             # Pre-migration backups of overwritten target files
├── runtimes/                      # Explicitly installed user-space runtimes for MCP helpers and Computer Use
│   └── cua-driver/                # Pinned, checksum-verified private Cua executable and install manifest
├── skill_versions/                # Skill patch backups for skill hub and controlled self-evolution flows
├── row_bot_app.log                  # Structured application log
├── splash.log                     # Splash-screen diagnostics
├── inbox/                         # Files received via messaging channels
├── browser_profile/               # Persistent Chromium profile
├── browser_history.json           # Display-safe browser history and snapshots with sensitive typed/action values redacted
├── designer/
│   ├── projects/                  # Designer project JSON files
│   ├── references/                # Designer source/reference uploads
│   ├── assets/                    # Persistent project assets
│   └── published/                 # Published HTML bundles and shareable output
├── tracker/
│   ├── tracker.db                 # Habit and health tracker database
│   └── exports/                   # CSV exports for tracker charts
├── vector_store/                  # Uploaded document vector index
│   └── embedding_metadata.json     # Embedding provider/dimension metadata for stale-index detection
├── gmail/                         # Gmail OAuth tokens
├── calendar/                      # Calendar OAuth tokens
├── wiki/                          # Obsidian-compatible markdown vault export
├── x/                             # X OAuth tokens and tier metadata
├── installed_plugins/             # Marketplace-installed plugins
├── plugin_state.json              # Plugin config, marketplace metadata, health, settings, and enablement state
├── plugin_secrets.json            # Plugin API-key metadata only; raw key values live in the OS credential store when available
├── recovery/                      # Backups created by task/local DB reset and restore helpers
└── kokoro/                        # Kokoro TTS model and voice files

Override the data directory by setting the ROW_BOT_DATA_DIR environment variable.

Comparison with Other Tools

Why not just use another open-source assistant?

Most open-source AI assistants are still developer tools disguised as products — CLI-first, config-file-driven, and built around Docker, YAML, and environment variables. Getting started often means cloning repos, editing configs, wiring databases, and debugging dependencies before you can ask a single useful question.

Row-Bot is different. It is packaged as a native desktop experience with one-click installers for Windows and macOS, a one-line Linux installer backed by a verified XDG tarball, local-first defaults, a pairing-gated mobile companion, opt-in native Computer Use, and a GUI that exposes models, tools, Goal Mode, Agent Profiles, bounded child-agent delegation, workflows, channels, Designer Studio, Developer Studio, Smart Skills, Skills Hub, Custom Tools, controlled self-evolution, and memory without requiring terminal fluency.

Why not just use ChatGPT?

ChatGPT / Claude / GeminiRow-Bot
Your dataStored on provider servers, subject to their privacy policiesStays on your machine. With opt-in provider/custom models, only the current conversation and model-visible tool context go to the selected endpoint; memories, files, designer projects, and history remain local unless explicitly included
ConversationsProvider-owned chat historyLocal SQLite-backed threads, exportable anytime
Mobile accessProvider-hosted account and cloud relayDirect connection to your running Row-Bot host through LAN, Tailscale, or an explicit tunnel, protected by revocable device pairing and local auth storage
CostSubscription or provider billingFree with local models; provider/custom usage is upstream API billing, self-hosted infrastructure, or ChatGPT / Claude / xAI Grok subscription access only when you opt in
MemoryLimited, opaque, provider-controlledPersonal knowledge graph with entities, relations, bounded recall, audit/review states, visualization, wiki export, and background refinement
Agent orchestrationOne assistant persona with limited delegation visibilityGoal Mode, Agent Profiles, child-agent delegation, durable Agent Runs, checkpoint-safe work budgets, configurable nesting/concurrency/active-time limits, profile/tool allowlists, and promoted Agent-run workflows stay local and reviewable
ToolsLimited app integrations and provider-defined plug-ins30+ core tools plus Agent/Goal tools, Developer-native tools, Custom Tool Builder, promoted Custom Tools, Smart Skills, Skills Hub imports, and auto-generated channel tools: shell, browser, opt-in native Computer Use, filesystem, Gmail, Calendar, memory graph, Designer Studio, Row-Bot Status, MCP external tools, image generation, video generation, research tools, and more
CustomizationPick a model and maybe a custom instructionSwap provider-qualified models per thread, profile, workflow, child-agent run, or Developer workspace, configure name and personality, build workflows, toggle and pin tools/skills, install skills from Skills Hub, create Custom Tools from repos/folders, and use controlled self-evolution proposals
VoiceUsually cloud-processedLocal faster-whisper STT plus Kokoro TTS, with a separate realtime voice runtime for provider-backed conversational sessions
AvailabilityInternet requiredLocal models work offline; hosted providers and custom endpoints are optional

Bottom line: cloud assistants rent you access to someone else's system. Row-Bot gives you personal AI sovereignty — local durable state, provider choice when you want it, and all of your long-lived data under your own control.

How is Row-Bot different from OpenClaw?

OpenClaw is a strong open-source personal assistant aimed at multi-channel delivery and developer-centric workflows. The two projects overlap in ambition but optimize for different users.

Row-BotOpenClaw
Getting startedOne-click installers and GUI-first setup on Windows and macOS, plus one-line Linux install with browser-first launchCLI-oriented install flow and heavier terminal expectations
Model routingLocal-first data with local, hosted, OpenCode, OpenRouter, Atlas Cloud, xAI Grok OAuth, ChatGPT / Codex, Claude Subscription, Ollama Cloud, live Atlas/MiniMax/xAI discovery, capability labels, chat-only fallbacks, and custom OpenAI-compatible model paths in one GUIMore cloud-first in typical setups
Agent orchestrationGoal Mode, Agent Profiles, child-agent delegation, durable Agent Runs, checkpoint-safe work/delegation limits, profile/tool allowlists, and Agent-run workflow promotionDifferent orchestration model with less desktop-first profile/goal visibility
MemoryTyped personal knowledge graph with bounded recall, audit/review states, visualization, wiki export, and structured relationsSimpler text-centric memory patterns
Knowledge refinement5-phase Dream Cycle with merge, enrich, decay, infer, and insight passesExperimental dreaming-style memory promotion flows
Document intelligenceStructured graph extraction with provenance, dedup, and relation typingStrong workspace tools but less graph-centric document knowledge modeling
Designer / CanvasDesigner Studio for decks, one-pagers, reports, published links, plus inline Mermaid and Plotly renderingA2UI-style interactive workspace focus
Developer / CodeDeveloper Studio for Git workspaces with code threads, approval modes, file tree, todos, diffs, tests, GitHub/PR prep, and optional Docker shadow sandboxDeveloper-heavy CLI and terminal-first workflows
Tools30+ core tools plus Agent/Goal tools, Developer-native tools, opt-in native Computer Use, Smart Skills, Skills Hub, Custom Tool Builder, promoted Custom Tools, and auto-generated channel send tools, including Designer Studio, Row-Bot Status, and MCP external toolsBroad built-in toolset with different emphasis
Messaging channels5 bundled channels with platform-aware live streaming/edit fallback, media handling, interactive/text approvals, durable terminal notices, and a sidebar monitorWider channel catalog and gateway focus
Autonomous workflowsStep-based workflows with approvals, conditions, triggers, concurrency groups, safety modes, Agent Profile overrides, and promotion from completed Agent RunsStrong channel routing and automation, different orchestration model
Desktop experienceNative Windows and macOS desktop app with tray, splash, setup wizard, and opt-in native Computer Use/live takeover; Linux browser-first package with optional native/tray modes; pairing-gated mobile companion served by the running hostMore developer-first and channel-first in practice
Privacy postureAll durable state local; no Row-Bot servers or first-party telemetry; optional Cua Driver telemetry is separately disclosed and consent-gatedSelf-hostable and privacy-conscious, but with a different operational model

In short: OpenClaw is an excellent multi-channel gateway for developer-heavy setups. Row-Bot is optimized for personal AI sovereignty — local-first memory, structured knowledge, visible goals, reusable Agent Profiles, child-agent delegation, integrated design and code workspaces, user-created tools, configurable self-knowledge, and a native desktop experience that does not require living in a terminal.