# rho [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mikeyobrien/rho) [![@tau_rho_ai](https://img.shields.io/badge/@tau__rho__ai-000000?logo=x)](https://x.com/tau_rho_ai) An always-on personal AI operator that: - stays running in the background, - remembers context across sessions, - and checks in proactively on a schedule. Runs on **macOS**, **Linux**, and **Android** (plus **iPhone/iPad via SSH**).

rho web ui

Built on [pi coding agent](https://github.com/badlogic/pi-mono).
Terminal demo ![Rho demo](docs/demo.gif)
--- ## Why rho Most AI tools are stateless chat tabs. rho is built for ongoing operation. - **Persistent memory**: durable context across sessions - **Memory observability**: inspect, search, and edit what the agent has learned - **Proactive heartbeat**: check-ins every 30m by default - **Local-first state**: your memory and config stay on your machine - **BYO model/provider**: use your own pi/provider setup - **Multi-surface control**: terminal, web UI, Telegram, and agent email --- ## 2-minute quick start (recommended) Prerequisites: **Node.js 18+**, **tmux**, **git** ```bash npm install -g @rhobot-dev/rho rho init && rho sync rho login && rho start rho ``` That gives you: - initialized config in `~/.rho/` - authenticated provider access via pi - background heartbeat daemon - an attached interactive session ### First 5 minutes Run these after install: ```bash rho status # daemon + module health /rho status # heartbeat status (inside session) /rho now # trigger immediate check-in /brain # open memory viewer /vault inbox # see captured knowledge items ``` --- ## Web UI (first-class, built in) rho includes a browser workspace for day-to-day operation: - chat with real-time streaming responses - session browsing + forking from any message - memory management (`/brain` entries) - task management - config editing (`~/.rho/init.toml`) - line-level code review at `/review` ### Lightweight + performant by design - **No-build web split**: server logic in `web/*.ts`, browser runtime in `web/public/js/*.js` (no frontend bundler/transpile pipeline). - **Lean server runtime**: Hono-based routes with response compression enabled. - **Low-latency updates**: live RPC/WebSocket streaming for chat responses. - **Push over poll where possible**: server emits `sessions_changed` UI events; client updates immediately. - **Idle-aware behavior**: polling pauses when the tab is hidden or user is idle, then resumes on activity. - **Render throttling for streams**: markdown updates are debounced (150ms) to reduce UI churn during rapid token deltas. - **Session metadata caching**: session info is cached by file `mtime` to avoid unnecessary re-reads. ```bash rho web rho web --port 4000 rho web --open ``` Then open `http://localhost:3141` (or your host IP). ### Positioning vs OpenClaw / nanobot | Project | Web experience emphasis | |---|---| | **rho** | Built-in operator workspace with stronger memory observability and a lightweight no-build stack (chat, learned-memory inspection/editing, tasks, config, review) | | **OpenClaw** | Strong Gateway Control UI + WebChat control plane | | **nanobot** | README primarily emphasizes CLI + channel gateway flows | --- ## Install alternatives
pi package install ```bash pi install npm:@rhobot-dev/rho rho init && rho sync rho login && rho start ```
macOS / Linux (installer script) ```bash git clone https://github.com/mikeyobrien/rho.git ~/.rho/project cd ~/.rho/project && ./install.sh ``` The installer checks missing dependencies and supports NixOS.
Android (Termux) Install [Termux](https://f-droid.org/packages/com.termux/) and [Termux:API](https://f-droid.org/packages/com.termux.api/) from F-Droid, then: ```bash curl -fsSL https://rhobot.dev/install | bash ``` If Termux can't build the optional `node-pty` native module, rho still installs and runs. Only the embedded web terminal drawer is disabled until `node-pty` works on that device.
iPhone / iPad via SSH Run rho on a server/VPS/home machine, then connect from iOS using Termius (or any SSH client). Guide: [docs/iphone-setup.md](docs/iphone-setup.md)
--- ## What you can do with rho | Use case | What rho does | |---|---| | **Daily operator loop** | Keeps reminders/tasks alive between sessions and runs periodic check-ins | | **Memory-backed coding copilot** | Stores durable behavior/preferences/learnings, and lets you inspect/edit that learned state directly | | **Inbox agent** | Gets `name@rhobot.dev`, polls, reads, and replies to email | | **Telegram-controlled agent** | Receives prompts from Telegram and responds in-thread | | **Browser control panel** | Web UI for chat, memory, tasks, and config | --- ## Mobile Live Mode (native Android wrapper) If you use the native Android wrapper (`mobile/rho-android`) to run rho-web, background behavior has two explicit modes: - **Idle Mode (default):** best battery behavior. No always-on background socket while the app is backgrounded; reconnect + replay happens when the app becomes active again. - **Live Mode (GO LIVE):** starts an Android foreground service with a persistent notification and lease heartbeats to keep active streams alive while locked/backgrounded. Use **Live Mode** when stream continuity matters (for example, long active responses while the phone is locked). Without it, WebView background limits can cause disconnect/orphan behavior around the default orphan window. Tradeoffs: - higher battery/network usage while Live Mode is active, - persistent foreground notification, - explicit user-controlled lifecycle (`GO LIVE` / `STOP LIVE`). Baseline Live Mode reliability does **not** require Firebase credentials. --- ## Surfaces and modules ### Core runtime - **Heartbeat**: scheduled autonomous check-ins - **Brain**: append-only structured memory (`brain.jsonl`) - **Vault**: markdown knowledge graph (`~/.rho/vault/`) ### Channels - **Email**: agent inbox at `name@rhobot.dev` - **Telegram**: polling adapter with allowlist + moderation flow ### Interface - **CLI**: `rho ...` commands - **Session slash commands**: `/rho`, `/brain`, `/vault`, `/skill`, `/telegram`, `/email` - **Web UI**: chat + memory/tasks/config in browser --- ## Security and ownership model - **Your memory is local** (`~/.rho/brain/brain.jsonl`) - **Your config is local** (`~/.rho/init.toml`, `~/.rho/packages.toml`) - **Your providers are yours** (`rho login` via pi) - **Telegram controls**: allowlists and mention gating - **Email controls**: sender controls + outbound policy limits No hosted rho memory backend required. --- ## Command quick reference ```bash rho # start and attach rho init # initialize ~/.rho config rho sync # sync rho config to pi rho doctor # health + config checks rho login # authenticate providers rho start # start background daemon rho stop # stop daemon rho status # daemon/module status rho trigger # force heartbeat now rho logs # recent heartbeat output rho config # show effective config rho calc "2 + 2 * 3" # quick arithmetic calculator rho upgrade # update and resync rho skills # skills provider wrapper ``` Inside a session: ```text /rho status heartbeat state /rho now immediate check-in /rho interval 30m set check-in interval /rho enable/disable toggle heartbeat /bootstrap status bootstrap lifecycle state /brain memory operations /vault inbox captured vault items /skill run pdd planning workflow /skill run code-assist implementation workflow ``` --- ## Platform support | Platform | Status | Notes | |---|---|---| | Linux | Supported | Native install + daemon + web UI | | macOS | Supported | Native install + daemon + web UI | | Android (Termux) | Supported | Extra mobile capabilities via platform skills | | iPhone/iPad | Supported (SSH client) | Run rho remotely, connect via SSH | --- ## Docs map - [Demo walkthrough](docs/demo.md) - [Telegram setup + troubleshooting](docs/telegram.md) - [iPhone/iPad setup](docs/iphone-setup.md) - [Android mobile app over Tailscale](docs/mobile-tailscale.md) - [VPS setup guide](docs/vps-setup.md) - [Skills providers (vercel + clawhub)](docs/skills.md) - [Brain bootstrapping guide](docs/bootstrapping-brain.md) - [Configuration reference](docs/configuration.md) --- ## For contributors Project structure and internals are intentionally modular: - `cli/` for command surface and daemon orchestration - `extensions/` for runtime tools/modules - `skills/` for portable markdown runbooks - `platforms/` for platform-specific installs/capabilities - `web/` for browser UI + RPC bridge For full tree + extension/skill details, see current `README.md` and `docs/`. --- ## Links - [pi coding agent](https://github.com/badlogic/pi-mono) - [@tau_rho_ai](https://x.com/tau_rho_ai)