# README Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Write three open-source documentation files: README.md, docs/INSTALL.md, docs/SECURITY.md

**Architecture:** Three standalone markdown files. README is the entry point (~120-150 lines), linking out to INSTALL.md and SECURITY.md for details. No code changes.

**Tech Stack:** Markdown

**Spec:** `docs/superpowers/specs/2026-04-08-readme-design.md`

---

### Task 1: Write README.md

**Files:**
- Create: `README.md`

- [ ] **Step 1: Write the full README.md**

```markdown
# RightClaw 🫱

Multi-agent runtime for Claude Code. Sandboxed. Subscription-compliant. Everything in chat.

## Prerequisites

> Full installation guide: [docs/INSTALL.md](docs/INSTALL.md)

**Required:**
- [Rust](https://rustup.rs/) toolchain
- [process-compose](https://github.com/F1bonacc1/process-compose) v1.100.0+
- [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (authenticated)
- Telegram bot token (via [@BotFather](https://t.me/BotFather))

**Highly recommended:**
- [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) (authenticated, with a named tunnel)

## Quick Start

```sh
cargo install --path crates/rightclaw-cli
rightclaw init --telegram-token <YOUR_BOT_TOKEN>
rightclaw up
```

This launches your first agent inside an NVIDIA OpenShell sandbox, accessible via Telegram.

## What Is This?

RightClaw orchestrates multiple independent Claude Code sessions, each running inside its own [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox. It calls `claude -p` directly — your existing Claude subscription works as-is, no token arbitrage, no API key sharing. Because it builds on Claude Code rather than replacing it, you get native features for free: memory, skills, MCP. On top of that, RightClaw adds its own persistent memory store (SQLite with FTS5/BM25 search), declarative cron scheduling, and agent personalities. OpenShell sandboxes are Docker containers — easy to back up, snapshot, and migrate. Everything is managed through Telegram, including Claude login and MCP OAuth authorization.

## Features

### Runtime

- **Multi-agent orchestration** — process-compose TUI to provision and monitor all agents from a single screen
- **Declarative cron engine** — YAML-defined scheduled tasks with run tracking and Telegram notifications
- **Restart policies** — `on_failure`, `always`, `never` with configurable backoff
- **Diagnostics** — `rightclaw doctor` validates dependencies, sandbox health, MCP status, and tunnel connectivity
- **Media attachments** — files flow both directions between Telegram and your agents

### Developer Experience

- **Claude skills ecosystem** — compatible with [skills.sh](https://skills.sh) skill format
- **MCP support** — automatic OAuth token refresh, add/remove servers via chat
- **Everything-in-chat** — Claude login, MCP OAuth, bot commands — no terminal needed after `rightclaw up`
- **Agent personalities** — onboarding flow where each agent discovers its own identity and tone
- **Persistent memory** — per-agent SQLite store with full-text search (FTS5/BM25)

### Security

NVIDIA OpenShell containers per agent, credential isolation, declarative network and filesystem policies, prompt injection detection. See [Security Model](docs/SECURITY.md) for the full picture.

### Compliance

- Calls `claude -p` directly — works with your existing Claude subscription
- No token arbitrage, no API key sharing, fully compliant with Anthropic's Terms of Service

## Roadmap

- [x] Multi-agent orchestration (process-compose)
- [x] NVIDIA OpenShell sandbox per agent
- [x] Telegram bot interface
- [x] Persistent memory (SQLite FTS5/BM25)
- [x] MCP support with OAuth token refresh
- [x] Claude login via chat
- [x] MCP OAuth via chat
- [x] Declarative cron engine
- [x] Agent personality / onboarding
- [x] Media attachments (both directions)
- [x] Restart policies with backoff
- [x] `rightclaw doctor` diagnostics
- [x] Claude skills ecosystem compatibility
- [ ] Telegram group chats
- [ ] Telegram chat threads
- [ ] Agent-to-agent communication
- [ ] Binary distribution (homebrew, nix, releases)
- [ ] Google Chrome integration
- [ ] Karpathy's LLM Wiki integration
```

- [ ] **Step 2: Verify line count is within target**

Run: `wc -l README.md`
Expected: between 80 and 150 lines

- [ ] **Step 3: Commit**

```bash
git add README.md
git commit -m "docs: add README for open-source release"
```

---

### Task 2: Write docs/INSTALL.md

**Files:**
- Create: `docs/INSTALL.md`

- [ ] **Step 1: Write the full docs/INSTALL.md**

```markdown
# Installation

## Prerequisites

### Rust Toolchain

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

RightClaw uses Rust edition 2024. Any recent stable toolchain will work.

### process-compose

Process orchestrator that powers multi-agent management. Version **1.100.0+** required.

```sh
# macOS
brew install f1bonacc1/tap/process-compose

# Linux — download from GitHub releases
# https://github.com/F1bonacc1/process-compose/releases
```

### NVIDIA OpenShell

Sandbox runtime for agent isolation. Currently in alpha.

```sh
# Follow install instructions at:
# https://github.com/NVIDIA/OpenShell
# https://docs.nvidia.com/openshell/latest/index.html
```

Requires Docker. OpenShell runs k3s containers inside Docker.

### Claude Code CLI

```sh
npm install -g @anthropic-ai/claude-code
claude  # follow prompts to authenticate
```

You must have an active Claude subscription. RightClaw calls `claude -p` directly — no API keys needed.

### Telegram Bot Token

1. Open [@BotFather](https://t.me/BotFather) in Telegram
2. Send `/newbot`, follow prompts
3. Save the bot token — you'll pass it to `rightclaw init`

### cloudflared (Highly Recommended)

Required for Telegram webhook tunneling. Without it, your bot needs a publicly reachable IP.

```sh
# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
# https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/
```

After installing, authenticate and create a named tunnel:

```sh
cloudflared tunnel login
cloudflared tunnel create rightclaw
```

## Build from Source

```sh
git clone https://github.com/anthropics/rightclaw.git
cd rightclaw
cargo install --path crates/rightclaw-cli
```

> Binary distribution via homebrew, nix, and GitHub releases is coming soon.

## Setup

```sh
# Initialize with your Telegram bot token
rightclaw init --telegram-token <YOUR_BOT_TOKEN>

# Verify everything is configured correctly
rightclaw doctor

# Launch your agents
rightclaw up
```

`rightclaw doctor` checks all dependencies, validates agent configuration, verifies sandbox connectivity, MCP status, and tunnel health. Run it whenever something seems off.
```

- [ ] **Step 2: Commit**

```bash
git add docs/INSTALL.md
git commit -m "docs: add installation guide"
```

---

### Task 3: Write docs/SECURITY.md

**Files:**
- Create: `docs/SECURITY.md`

- [ ] **Step 1: Write the full docs/SECURITY.md**

```markdown
# Security Model

RightClaw enforces security at the infrastructure level. Every agent runs inside an isolated container with declarative policies — not through permission prompts or trust-based configuration.

## Sandbox Architecture

Each agent runs inside its own [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox — a k3s container managed via gRPC. Sandboxes are persistent (survive bot restarts) and isolate:

- **Filesystem** — agents can only access paths explicitly allowed by policy
- **Network** — all traffic routes through an HTTPS proxy (`10.200.0.1:3128`) with domain allowlists
- **Credentials** — each sandbox has its own authentication state, independent of the host
- **Processes** — agent processes are contained within the sandbox boundary

Sandboxes are Docker containers. Back them up, snapshot them, migrate them — standard container operations apply.

## Credential Isolation

Host credentials (`.credentials.json`) are **never** uploaded to sandboxes. Each agent authenticates independently through an OAuth login flow that happens entirely inside the sandbox. The login flow is PTY-driven and managed through Telegram — the user receives an OAuth URL, clicks it, and pastes the auth code back in chat.

MCP OAuth tokens are stored per-agent and refreshed automatically (10 minutes before expiry). Token refresh happens on the host and the updated `.mcp.json` is uploaded to the sandbox.

## Network Policy

All sandbox network traffic goes through OpenShell's HTTPS proxy:

- **Domain allowlists** — wildcard patterns (e.g., `*.anthropic.com`, `*.claude.ai`) control which endpoints agents can reach
- **TLS termination** — the proxy terminates and re-signs TLS with a per-sandbox CA for L7 inspection. Required on all HTTPS endpoints (OpenShell v0.0.23+).
- **Policy hot-reload** — network rules can be updated without restarting the sandbox via `openshell policy set --wait`

## Declarative Policies

Each agent gets a generated policy file controlling:

- **Filesystem rules** — read/write paths, binary execution paths
- **Network rules** — allowed domains, allowed IPs, TLS termination settings
- **Binary restrictions** — which executables the agent can run (`path: "**"` for full access, or locked down per-binary)

Policies are regenerated on each `rightclaw up` from `agent.yaml` configuration and sandbox override settings.

## Prompt Injection Guard

The memory store (SQLite) runs incoming content through pattern matching based on OWASP prompt injection vectors before insert. Detected injection attempts are rejected before they reach the database.

## Access Control

- **Chat ID allowlist** — each agent has a per-agent list of allowed Telegram chat IDs. Empty list = block all (secure default).
- **Protected MCP servers** — the built-in "right" MCP server cannot be removed via `/mcp remove`
- **OAuth CSRF protection** — token matching in the OAuth callback server prevents cross-site request forgery

## Compliance

RightClaw calls `claude -p` directly, using your existing Claude subscription. There is no token arbitrage, no API key sharing, and no man-in-the-middle on Claude's authentication. This makes RightClaw fully compliant with Anthropic's Terms of Service.
```

- [ ] **Step 2: Commit**

```bash
git add docs/SECURITY.md
git commit -m "docs: add security model documentation"
```

---

### Task 4: Final review and combined commit

- [ ] **Step 1: Read all three files and verify cross-references**

Check that:
- README.md links to `docs/INSTALL.md` and `docs/SECURITY.md` — both paths correct
- INSTALL.md doesn't duplicate README content unnecessarily
- SECURITY.md covers all items listed in the spec

- [ ] **Step 2: Verify README line count**

Run: `wc -l README.md`
Expected: between 80 and 150 lines
