{"id":43463628,"url":"https://github.com/mikeyobrien/rho","last_synced_at":"2026-02-25T06:47:09.499Z","repository":{"id":336163126,"uuid":"1148511700","full_name":"mikeyobrien/rho","owner":"mikeyobrien","description":"An AI agent that stays running, remembers across sessions, and checks in on its own. macOS, Linux, Android. Built on Pi.","archived":false,"fork":false,"pushed_at":"2026-02-17T01:33:08.000Z","size":3331,"stargazers_count":251,"open_issues_count":1,"forks_count":19,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-17T04:39:13.286Z","etag":null,"topics":["pi-coding-agent"],"latest_commit_sha":null,"homepage":"https://rhobot.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikeyobrien.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["mikeyobrien"]}},"created_at":"2026-02-03T03:39:05.000Z","updated_at":"2026-02-17T03:14:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mikeyobrien/rho","commit_stats":null,"previous_names":["mikeyobrien/rho"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/mikeyobrien/rho","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Frho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Frho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Frho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Frho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikeyobrien","download_url":"https://codeload.github.com/mikeyobrien/rho/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Frho/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29697476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T18:18:25.093Z","status":"ssl_error","status_checked_at":"2026-02-21T18:18:22.435Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pi-coding-agent"],"created_at":"2026-02-03T06:04:46.739Z","updated_at":"2026-02-21T23:16:43.430Z","avatar_url":"https://github.com/mikeyobrien.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mikeyobrien"],"categories":["Personal Assistants","Lightweight"],"sub_categories":[],"readme":"# rho\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/mikeyobrien/rho)\n[![@tau_rho_ai](https://img.shields.io/badge/@tau__rho__ai-000000?logo=x)](https://x.com/tau_rho_ai)\n\nAn AI agent that stays running, remembers what you told it yesterday, and checks in on its own. Runs on macOS, Linux, and Android.\n\nYour data stays on your device. No cloud for your memories. Bring your own LLM provider. You own everything.\n\nBuilt on [pi coding agent](https://github.com/badlogic/pi-mono).\n\n![Rho demo](docs/demo.gif)\n\n## Quick start\n\n### Install with your agent\n\nAsk your coding agent to fetch and follow the [install runbook](https://raw.githubusercontent.com/mikeyobrien/rho/main/SKILL.md).\n\n### npm\n\n```bash\nnpm install -g @rhobot-dev/rho\nrho init \u0026\u0026 rho sync\nrho login \u0026\u0026 rho start\n```\n\n### pi\n\n```bash\npi install npm:@rhobot-dev/rho\nrho init \u0026\u0026 rho sync\nrho login \u0026\u0026 rho start\n```\n\nPrerequisites for both: Node.js (18+), tmux, git.\n\n### macOS / Linux\n\n```bash\ngit clone https://github.com/mikeyobrien/rho.git ~/.rho/project\ncd ~/.rho/project \u0026\u0026 ./install.sh\n```\n\nPrerequisites: Node.js (18+), tmux, git. The installer checks and tells you what's missing. NixOS is detected and supported.\n\n### Android (Termux)\n\nInstall [Termux](https://f-droid.org/packages/com.termux/) and [Termux:API](https://f-droid.org/packages/com.termux.api/) from F-Droid, then:\n\n```bash\ncurl -fsSL https://rhobot.dev/install | bash\n```\n\nOr step by step:\n\n```bash\npkg install nodejs-lts tmux git\nnpm install -g @mariozechner/pi-coding-agent\ngit clone https://github.com/mikeyobrien/rho.git ~/.rho/project\ncd ~/.rho/project \u0026\u0026 ./install.sh\n```\n\n### iPhone / iPad (via SSH)\n\nRho runs on a server you SSH into. Use [Termius](https://apps.apple.com/app/termius-terminal-ssh-client/id549039908) or any SSH client.\n\n```bash\n# On your server (VPS, home machine, or free Oracle Cloud instance):\ngit clone https://github.com/mikeyobrien/rho.git ~/.rho/project\ncd ~/.rho/project \u0026\u0026 ./install.sh\nrho login \u0026\u0026 rho start\n\n# On your iPhone: connect via SSH, then:\nrho\n```\n\nFull guide: [docs/iphone-setup.md](docs/iphone-setup.md), including Termius config, Tailscale for home servers, and free VPS options.\n\n## Run\n\n```bash\nrho                      # Start and attach\nrho init                 # Initialize Rho config in ~/.rho/\nrho sync                 # Sync config to pi settings.json\nrho doctor               # Check system health and config validity\nrho login                # Authenticate with pi providers\nrho start                # Start in background\nrho stop                 # Stop\nrho status               # Show daemon and module status\nrho trigger              # Force an immediate heartbeat check-in\nrho config               # Show current configuration\nrho logs                 # Show recent heartbeat output\nrho upgrade              # Update Rho and sync new modules\n```\n\nInside a session:\n\n```\n/rho status              Show heartbeat state\n/rho now                 Trigger check-in immediately\n/rho interval 30m        Set check-in interval\n/rho enable/disable      Toggle heartbeat\n/bootstrap status        Show bootstrap state + managed count + last operation\n/bootstrap run           Run bootstrap apply (non-interactive defaults)\n/bootstrap diff --to pa-v2\n                         Preview merge/upgrade actions\n/bootstrap reapply       Re-apply current bootstrap profile\n/bootstrap upgrade --to pa-v2\n                         Upgrade profile pack version\n/bootstrap reset --confirm RESET_BOOTSTRAP\n                         Reset bootstrap state safely\n/bootstrap audit         Show recent bootstrap lifecycle events\n/subagents               Check spawned subagent status\n/vault inbox             View captured items\n/brain                   Interact with memory\n/skill run pdd           Run the Prompt-Driven Development workflow\n/skill run code-assist   Run the code implementation workflow\n```\n\n## What it does\n\nThe **heartbeat** checks in periodically (default: every 30 min). Each check-in reads reminders and tasks from the **brain**, runs what needs running, and reports back.\n\nThe **brain** persists across sessions as a single `brain.jsonl` file. It stores behaviors, identity, learnings, preferences, tasks, reminders, and context — everything the agent needs to remember.\n\n**Agent email** gives your agent a real email address at `name@rhobot.dev`. People and services can email your agent directly. The agent polls its inbox, reads messages, and can reply. Free tier gets receive + 1 outbound email per hour. Register with:\n\n```\nAsk your agent: \"Set up my agent email at \u003cname\u003e@rhobot.dev\"\n```\n\nOr use the `/email` command once registered:\n\n```\n/email check        Poll inbox for new mail\n/email list         Show unread messages\n/email send \u003cto\u003e \u003csubject\u003e   Send a quick email\n```\n\n**Telegram channel adapter** lets the agent receive prompts from Telegram and reply in-thread.\n\nQuick setup:\n\n```bash\n# 1) Set bot token in your shell profile\nexport TELEGRAM_BOT_TOKEN=\"\u003cbot-token\u003e\"\n\n# 2) Enable in ~/.rho/init.toml\n# [settings.telegram]\n# enabled = true\n\nrho sync\nrho telegram onboard\nrho telegram start\n```\n\nOperator controls:\n\n```\n/telegram status\n/telegram check\n/telegram allow-chat \u003cchat_id\u003e\n/telegram allow-user \u003cuser_id\u003e\n```\n\nCommon Telegram shortcuts:\n\n```\n/status    -\u003e /telegram status\n/check     -\u003e /telegram check\n/telegram  -\u003e /telegram status\n```\n\nApproval flow for blocked senders:\n\n```bash\nrho telegram pending\nrho telegram approve --pin 123456\nrho telegram reject --pin 123456\n```\n\nSecurity model (MVP):\n- Polling-only transport (`getUpdates`) with durable offset state\n- Optional `allowed_chat_ids` / `allowed_user_ids` gates\n- Group activation gate via `require_mention_in_groups`\n- Bounded retries for transient send failures and 429 rate-limits\n\nRollout notes:\n- MVP is polling-first; webhook mode is reserved for future work\n- Keep allowlists tight before exposing in group chats\n- If the module is disabled (`settings.telegram.enabled = false`), it is idle/no-op\n\nTroubleshooting:\n- `Missing token env`: export `TELEGRAM_BOT_TOKEN` (or your configured `bot_token_env`)\n- No group replies: mention the bot (or set `require_mention_in_groups = false`)\n- Delivery delays: check `/telegram status` for retry/failure counters\n- Long prompts: foreground soft-timeout (`rpc_prompt_timeout_seconds`) now forks work into durable `/jobs` tasks; use `/jobs`, `/job \u003cid\u003e`, `/cancel \u003cid\u003e` to manage long-running work\n\nSee full setup and smoke validation guide: [docs/telegram.md](docs/telegram.md).\n\n**Skills** are capability packages the agent loads on demand. The installer detects your OS and installs the right ones. Notifications, clipboard, and text-to-speech work on every platform. Android gets SMS, speech-to-text, camera, GPS, and Tasker automation on top of that.\n\n### Skills\n\n| Skill | Android | macOS | Linux | Description |\n|-------|:-------:|:-----:|:-----:|-------------|\n| `notification` | ✓ | ✓ | ✓ | System notifications |\n| `clipboard` | ✓ | ✓ | ✓ | Clipboard read/write |\n| `tts` | ✓ | ✓ | ✓ | Text-to-speech |\n| `open-url` | ✓ | ✓ | ✓ | Open URLs and apps |\n| `sms` | ✓ | | | Read and send SMS |\n| `stt` | ✓ | | | Speech-to-text |\n| `media` | ✓ | | | Audio, camera, recording |\n| `location` | ✓ | | | GPS/network location |\n| `contacts` | ✓ | | | Contact lookup |\n| `device` | ✓ | | | Battery, torch, vibration |\n| `dialog` | ✓ | | | Interactive input dialogs |\n| `tasker-xml` | ✓ | | | Create Tasker automations |\n| `rho-cloud-onboard` | ✓ | ✓ | ✓ | Register an agent email address |\n| `rho-cloud-email` | ✓ | ✓ | ✓ | Manage agent email address |\n| `memory-consolidate` | ✓ | ✓ | ✓ | Consolidate memory, decay stale entries, and mine sessions since last consolidation |\n| `update-pi` | ✓ | ✓ | ✓ | Update pi to latest version |\n\n### Extensions\n\n| Extension | Platforms | Description |\n|-----------|-----------|-------------|\n| `rho/` | All | Heartbeat, memory, tasks, vault tooling, plus workflow aliases (`/plan`, `/code`) |\n| `brave-search/` | All | Web search via Brave API |\n| `x-search/` | All | X (Twitter) search via xAI Grok (`x_search`) |\n| `telegram/` | All | Telegram adapter (polling MVP, chat/session bridge, operator controls) |\n| `email/` | All | Agent inbox at name@rhobot.dev |\n| `vault-search/` | All | Full-text search over the vault (FTS + ripgrep fallback) |\n| `memory-viewer/` | All | Browse and search memories |\n| `usage-bars/` | All | Token/cost usage display |\n| `tasker.ts` | Android | UI automation via Tasker |\n\n### Skills vs extensions\n\nSkills are markdown files. The agent reads them and follows the instructions using its built-in tools (bash, read, write, edit). No code runs. Think of them as runbooks. They're compatible with Claude Code and Codex too, since they follow the [Agent Skills spec](https://agentskills.io).\n\nSOPs are a **skill subtype** (`kind: sop` in frontmatter). Run them with `/skill run \u003cname\u003e` — there is no separate legacy sop command surface.\n\nExtensions are TypeScript that runs inside pi's process. They register new tools the LLM can call, hook into lifecycle events, persist state, add commands, and build custom UI. The heartbeat, the brain, and the vault are all extensions.\n\nIf the agent can already do it and just needs to know how, write a skill. If you need code running to make it possible, write an extension.\n\n## Web UI\n\n\u003cimg width=\"1816\" height=\"1530\" alt=\"image\" src=\"https://github.com/user-attachments/assets/83f73af7-9016-4a8a-887e-e736d779deaa\" /\u003e\n\n\nA browser-based interface for chatting, browsing memory, managing tasks, and editing config. Useful for phones, tablets, or any device on your network.\n\n```bash\nrho web                  # Start on default port (3141)\nrho web --port 4000      # Custom port\nrho web --open           # Start and open browser\n```\n\nThen visit `http://localhost:3141` (or your machine's IP for remote access — the server binds `0.0.0.0` by default).\n\n### Views\n\n| View | Description |\n|------|-------------|\n| **Chat** | Browse sessions, fork from any message, start new conversations. Model and thinking level selectable per session. |\n| **Memory** | Filter, search, create, edit, and delete brain entries (learnings, preferences, behaviors, etc.) |\n| **Tasks** | View and manage tasks from brain.jsonl |\n| **Config** | Edit `~/.rho/init.toml` directly in the browser |\n\nThe Chat view connects to pi over RPC and WebSocket — responses stream in real-time. Forking creates a branch from any user message in a session's history.\n\n### Code Review\n\nExtensions can open files for line-level review in the browser. The review UI supports multi-line selection, inline commenting, and submitting or cancelling. Access active reviews at `/review`.\n\n### Configuration\n\nAdd to `~/.rho/init.toml` to configure the web server:\n\n```toml\n[settings.web]\nport = 3141       # Server port (default: 3141)\nenabled = false   # Auto-start with `rho start`\n```\n\n## Customize\n\n### Brain\n\nEverything lives in `~/.rho/brain/brain.jsonl` — a single append-only log of structured entries:\n\n| Type | Stores |\n|---|---|\n| `behavior` | How the agent acts (do, don't, value) |\n| `identity` | Who the agent is |\n| `user` | Facts about the user |\n| `preference` | User likes/dislikes by category |\n| `learning` | Things discovered in sessions |\n| `context` | Project-specific settings |\n| `task` | Checklist items |\n| `reminder` | Time-based triggers |\n\n**Modify via the brain tool:**\n```\n/brain                           # Open memory viewer\nbrain action=add type=behavior category=do text=\"...\"\nbrain action=add type=reminder text=\"Check weather\" cadence={kind:\"daily\",at:\"08:00\"}\nbrain action=add type=task text=\"Review PRs\" priority=high\n```\n\n**Or edit directly** (the file is plain JSONL, one entry per line).\n\n### Auto-extraction\n\nThe `memory-consolidate` skill runs to:\n- **Decay** stale learnings (\u003e90 days, low score)\n- **Consolidate** duplicates and merge related entries\n- **Mine sessions** since the last consolidation checkpoint\n- **Relocate** reference-heavy entries to the vault for ad-hoc search\n\nRun manually:\n```\nRun memory-consolidate with session mining\n```\n\n\n### Vault\n\nFor reference material that needs structure (architecture docs, research, project overviews), use the vault:\n\n```\nvault write slug=my-project-arch type=concept\n```\n\nCreates markdown notes with wikilinks in `~/.rho/vault/`.\n\n## Tasker setup (Android, optional)\n\nFor UI automation (reading screens, tapping elements, controlling apps):\n\n1. Install [Tasker](https://play.google.com/store/apps/details?id=net.dinglisch.android.taskerm) and [AutoInput](https://play.google.com/store/apps/details?id=com.joaomgcd.autoinput)\n2. In Tasker: long-press home icon \u003e Import Project \u003e select `tasker/Rho.prj.xml`\n3. Enable the imported profiles\n\nOptional (screenshot without permission dialog):\n```bash\n# Enable wireless ADB in Developer Options, then:\nadb pair \u003cip\u003e:\u003cport\u003e \u003cpairing-code\u003e\nadb connect \u003cip\u003e:\u003cport\u003e\nadb shell appops set net.dinglisch.android.taskerm PROJECT_MEDIA allow\n```\n\n## Project structure\n\n```\nrho/\n├── cli/                     # Node.js CLI (rho init/sync/doctor/upgrade/...)\n│   ├── index.ts\n│   ├── config.ts\n│   ├── registry.ts\n│   ├── sync-core.ts\n│   ├── doctor-core.ts\n│   ├── daemon-core.ts\n│   └── commands/\n├── templates/               # Default ~/.rho/*.toml templates\n│   ├── init.toml\n│   └── packages.toml\n├── extensions/              # Core pi extensions (loaded via pi package entry)\n│   ├── brave-search/\n│   ├── email/\n│   ├── memory-viewer/\n│   ├── rho/\n│   ├── usage-bars/\n│   ├── vault-search/\n│   └── lib/                  # shared modules (NOT an extension)\n│       └── mod.ts            # barrel exports (do not name this index.ts)\n├── skills/                  # Core skills (loaded via pi package entry)\n│   ├── memory-consolidate/\n│   ├── pdd/\n│   ├── code-assist/\n│   ├── small-improvement/\n│   ├── vault-clean/\n│   ├── rho-cloud-email/\n│   ├── rho-cloud-onboard/\n│   ├── session-search/\n│   └── update-pi/\n├── platforms/               # Platform-only local skills/extensions installed by install.sh\n│   ├── android/\n│   │   ├── extensions/      # tasker.ts\n│   │   ├── skills/          # notification, clipboard, sms, stt, tts, ...\n│   │   └── scripts/bin/     # stt, stt-send\n│   ├── macos/\n│   │   ├── skills/          # notification, clipboard, open-url, tts\n│   │   └── setup.sh\n│   └── linux/\n│       ├── skills/          # notification, clipboard, open-url, tts\n│       └── setup.sh\n├── web/                     # Web UI server and frontend\n│   ├── server.ts            # Hono server (REST + WebSocket + RPC bridge)\n│   ├── rpc-manager.ts       # pi RPC process manager\n│   ├── config.ts            # Web config helpers\n│   └── public/              # Static assets (HTML, CSS, JS)\n├── configs/                 # Configuration files\n│   └── tmux-rho.conf        # SSH-friendly tmux config (used by rho's tmux socket)\n├── brain/                   # Default brain.jsonl with core behaviors\n├── tasker/                  # Importable Tasker profiles (Android)\n├── SKILL.md                 # Portable install skill (works with any agent)\n├── bootstrap.sh             # Universal installer (curl | bash)\n└── install.sh               # Cross-platform installer (platform extras + rho init/sync)\n```\n\n## Configuration\n\nDoom-style config lives in:\n- `~/.rho/init.toml` (modules + settings)\n- `~/.rho/packages.toml` (third-party pi packages)\n\n`install.sh` installs the `rho` command on your PATH (typically `$PREFIX/bin` on Termux or `~/.local/bin` on macOS/Linux).\n\nAfter editing either file, run:\n\n```bash\nrho sync\n```\n\n## Adding a platform\n\n1. Create `platforms/\u003cname\u003e/skills/` with SKILL.md files for the platform\n2. Optionally add `platforms/\u003cname\u003e/extensions/` for platform-specific extensions\n3. Optionally add `platforms/\u003cname\u003e/setup.sh` to check/install dependencies\n4. Add a detection case in `install.sh` (`detect_platform` function)\n5. Submit a PR\n\n## Environment variables\n\n```bash\nBRAVE_API_KEY=\"...\"     # For web search (optional)\n```\n\n## Links\n\n- [Brain bootstrapping guide](docs/bootstrapping-brain.md)\n- [Demo walkthrough](docs/demo.md)\n- [iPhone/iPad setup](docs/iphone-setup.md)\n- [VPS setup guide](docs/vps-setup.md)\n- [pi coding agent](https://github.com/badlogic/pi-mono)\n- [@tau_rho_ai](https://x.com/tau_rho_ai), Tau, an agent running on rho\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeyobrien%2Frho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeyobrien%2Frho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeyobrien%2Frho/lists"}