Update Readme

Author: Snehal-Reddy

README.md

@@ -1,46 +1,122 @@
-# iCrab
+# 🦀 iCrab
 
 ![iCrab](icrab.png)
 
-iCrab is a personal AI assistant that runs on an old iPhone inside iSH. You talk to it over Telegram. It uses your Obsidian vault (or any folder you point it at) as its workspace, so it can read your notes, log stuff, and search your daily logs. **One static binary, no webhooks, no open ports**. The kind of thing you run on a phone that was otherwise sitting in a drawer.
+> **A minimal, 100% private AI assistant running on a repurposed iPhone.**
 
-It is built to stay small and easy to extend.
+**iCrab** is a stripped down minimal personal AI assistant designed to run exclusively on an old iPhone inside [iSH](https://ish.app/). You interact with it via Telegram. It treats your Obsidian vault (or any local directory) as its workspace—giving it native access to read your notes, logs etc.
 
-## Why it exists
+It is built to stay small, extremely private, and effortlessly extensible.
 
-I wanted something that actually runs where I am, uses the notes I already keep, and does not depend on a cloud service. iSH on an iPhone gives you a 32-bit Linux userspace. iCrab is a single binary for that environment: Telegram long-poll in, agent loop with tools, everything stored in your workspace. Add a skill by dropping a `SKILL.md` in a folder. No plugins, no DLLs.
+**Key Highlights:**
+- **Zero Ingress:** No webhooks, no open ports. Uses Telegram long-polling.
+- **Single Static Binary:** Written in Rust, compiled to `i686-unknown-linux-musl`. **Extremely lightweight (~4.9MB).**
+- **Own Your Data:** Everything stays in your workspace. Chat history is stored locally in SQLite.
+- **Skill System:** Teach it new skills by simply dropping a `SKILL.md` file in a folder. No plugins, no code required.
 
-## Getting started
+---
 
-You need an iPhone with iSH and a stripped-down setup so the phone is not busy with iCloud and other services.
+## 💡 Why iCrab?
 
-**Pre-setup (iPhone wipe).** I won't go into privacy here, but read [the lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) from Simon Willison. Wipe anything important off the iPhone first.
+I tried a few options of OpenClaw alternatives. They were either too bloated or wouldn't simply work on 32 bit Alpine Linux. I wanted something that actually runs *where I am*, uses the notes I already keep, and doesn't depend on a cloud data lock-in, and is dead simple.
 
-- **Sign out of iCloud:** `Settings > [Your Name] > Sign Out`. That removes the device from Find My and disables Activation Lock.
-- **Erase All Content and Settings:** On modern iPhones this destroys the encryption keys; the data on the chip becomes unrecoverable.
-- **Do not sign in to iCloud again:** When it asks for an Apple ID, choose "Forgot password or don't have an Apple ID" then "Set Up Later in Settings." Keeps the phone light and stops background sync from hogging RAM.
-- **Disable everything:** During setup, say No to Face ID, Siri, Screen Time, and Analytics. You want the CPU available for iSH.
-- Optional: use a burner Apple account for the App Store only.
+---
 
-**Setup.** Download iSH on the iPhone.
+## ✨ Features
 
-**Build (on a real machine, from this directory `iCrab/`):**
+- **Telegram Interface:** Chat natively. It reads, thinks, uses tools, and replies.
+- **Workspace Integration:** Reads and writes files directly in your Obsidian vault. It knows what you wrote yesterday because it can read your daily notes.
+- **Local Memory & Search:** SQLite-backed persistence with FTS5. The agent can search your entire vault or your chat history blazingly fast.
+- **Background Subagents:** Tell it to "Search the web for X and summarize it." It spawns a background agent, freeing up the main chat, and messages you when it's done.
+- **Cron & Heartbeat:** Schedule recurring tasks or reminders (e.g., "Summarize unread messages every hour").
+- **Basic Tools:**
+  - `read_file`, `write_file`, `edit_file`, `append_file`, `list_dir`
+  - `web_search` (Brave API or DuckDuckGo) & `web_fetch`
+  - `cron` management
+  - Restricted `exec` (e.g., for `git pull` syncing)
 
-- Install [cross](https://github.com/cross-rs/cross): `cargo install cross`
-- `cross build` for debug, `cross build --release` for the binary you deploy.
+---
 
-Output: `target/i686-unknown-linux-musl/debug/icrab` or `.../release/icrab`. Put that in iSH, add your config (see below), and run it.
+## 🚀 Getting Started
 
-**Config:** One file, `~/.icrab/config.toml`. You set the workspace path (your Obsidian vault or a clone), your Telegram bot token, and the LLM (OpenRouter, OpenAI-compatible, etc.). Optional: Brave API key for web search, heartbeat interval, cron. No secrets in the binary; use the config file or env vars.
+To get started, you'll need an old iPhone with the iSH app installed, and a machine to compile the binary.
 
-## What it can do
+### 1. Prep your iPhone (The "Lethal Trifecta")
+Read Simon Willison's [lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) on device privacy.
 
-- **Chat over Telegram:** Long-poll only. You message the bot; it runs the agent and replies. No webhooks, no open ports.
-- **Use your workspace:** Read and write files under the workspace (e.g. daily logs, workouts,  notes). File tools are restricted to that tree.
-- **Remember and search:** MEMORY.md and daily notes are in context. Persistence (in progress) adds SQLite-backed chat history and FTS5 search over your vault so the agent can find "what did we say about X" quickly.
-- **Tools:** File (read, write, list, edit, append), web search and fetch, cron (reminders and one-off tasks), and a `message` tool to send you text. Optional: restricted `exec` for things like `git pull` in the vault.
-- **Subagents:** The agent can spawn a background task (e.g. "search the web and summarize"). The subagent runs with the same tools except no spawn; it reports back via `message` so you get the result in Telegram without blocking the main chat.
-- **Heartbeat:** A timer can read a file (e.g. `HEARTBEAT.md`) and run the agent on a schedule (e.g. "check my calendar" or "summarize unread").
-- **Skills:** Put a `SKILL.md` in `workspace/skills/<name>/`. The agent sees the list and can open a skill’s doc when it needs it. Extending is "add a folder and a markdown file."
+1. **Sign out of iCloud:** `Settings > [Your Name] > Sign Out`. Disables Activation Lock.
+2. **Erase All Content:** Destroys encryption keys, rendering old data unrecoverable.
+3. **Do not sign in again:** Choose "Set Up Later in Settings." This stops background sync from hogging RAM.
+4. **Disable extras:** Say No to Face ID, Siri, Screen Time, and Analytics.
 
-So: simple (one binary, one config, one ingress), light (static musl, minimal deps), and expandable (skills as docs, optional tools). If that matches what you want from a phone-bound assistant, the rest is in the design and persistence docs.
+Download **iSH** from the App Store (use a burner account if desired).
+
+### 2. Create your Telegram Bot
+1. Open Telegram and message [@BotFather](https://t.me/botfather).
+2. Send `/newbot` and follow the steps to get your **Bot Token**.
+3. Find your personal Telegram User ID (e.g., by messaging `@userinfobot`). You'll need this to ensure *only you* can talk to your bot.
+
+### 3. Build iCrab (On your computer)
+Because iSH runs a 32-bit x86 environment (`i686`), you must cross-compile.
+
+```bash
+# Clone the repository
+git clone https://github.com/Snehal-Reddy/iCrab.git
+cd iCrab
+
+# Install the cross-compiler tool
+cargo install cross
+
+# Build the release binary
+cross build --release
+```
+The compiled binary will be at `target/i686-unknown-linux-musl/release/icrab`. Transfer this file to your iPhone (via SSH into iSH, or start a local server and `curl`).
+
+### 4. Configuration
+Create a config file in your iSH environment at `~/.icrab/config.toml`:
+
+```toml
+# ~/.icrab/config.toml
+workspace = "~/.icrab/workspace"  # Point this to your Obsidian vault
+restrict-to-workspace = true
+
+[telegram]
+bot-token = "YOUR_TELEGRAM_BOT_TOKEN"
+allowed-user-ids = [123456789] # Your Telegram User ID
+
+[llm]
+provider = "openrouter"
+api-base = "https://openrouter.ai/api/v1"
+api-key = "YOUR_LLM_API_KEY"
+model = "google/gemini-3-flash-preview" # Or your preferred model
+
+[heartbeat]
+interval-minutes = 30
+timezone = "Europe/London" # Your IANA timezone
+```
+
+*(Note: You can also set secrets as environment variables like `TELEGRAM_BOT_TOKEN` and `ICRAB_LLM_API_KEY`.)*
+
+### 5. Run it!
+Inside iSH:
+```bash
+# Make it executable
+chmod +x icrab
+
+# Run it
+./icrab
+```
+Now, open Telegram, find your bot, and say "Hello"!
+
+---
+
+## 🧠 Teaching iCrab New Skills
+
+iCrab is designed to be easily extensible without writing code. To add a skill, simply create a folder in `workspace/skills/` and drop a `SKILL.md` file inside it.
+
+```text
+workspace/
+└── skills/
+    └── workout_logger/
+        └── SKILL.md
+```