# Remoko — Full Documentation (llms-full.txt)

> Concatenated documentation for LLMs and AI agents. Index: https://remoko.app/llms.txt

---

# Remoko — Overview & Quickstart

> Remoko is a remote control for your coding agents. It connects any MCP-capable agent to your iPhone and turns a blocking terminal prompt into a structured decision: risk level, consequences, recommendation. Answer in one tap and work resumes.

Canonical HTML page: https://remoko.app/docs

## What Remoko is

Agents rarely fail outright — they stall, waiting on a permission prompt or an ambiguous fork, silently, at a terminal nobody is looking at. Remoko moves *only the decisions* to your phone, not your workstation.

Remoko is:
- **Not a remote desktop.** No screen mirroring, no terminal, no typing code on a phone.
- **Not a chat client.** You do not converse with the agent. You answer it.
- **Not an agent.** Remoko never decides, never suggests-and-defaults, never acts.

"Remoko is not a terminal on your phone. It's a doorbell."

## How to get it

1. **Download the iOS app** (free, beta): https://testflight.apple.com/join/uSRmabxx (requires Apple's TestFlight app)
2. **Sign in** with your phone number and verify with the SMS code. No passwords; no email address required.
3. **Allow notifications** — Remoko relies on Apple Push Notifications to alert you to pending decisions.

## How to connect an agent

1. Open the **Connect** tab in the Remoko iOS app.
2. Copy your unique **MCP Endpoint URL** and **Access Token**.
3. Configure your agent client (Claude Code, Codex, Cursor, or any MCP client) to connect to that remote MCP server, sending the token on every request:

```
Authorization: Bearer remoko_tok_...
```

4. Have the agent call the `how_to_use` tool first — it returns the full reliability contract (idempotency, versioning, processed acknowledgments).

## What agents can do

| Tool intent | Description |
|---|---|
| Ask a question | Pose a question with optional predefined choices or free-text answers |
| Request approval | Propose an action with a risk level and wait for approve/deny |
| Send a check-in | Inform the owner of something; no response required |
| Update / cancel | Modify or cancel an existing request when it's no longer relevant |
| Report execution | Flow execution status (executing/completed/failed) back to the app |
| List unprocessed | Recover pending decisions after an agent restart |

Full reference: https://remoko.app/docs/mcp-tools.md

## Pricing

Remoko is free during the beta.

## More

- Security model: https://remoko.app/docs/security.md
- FAQ: https://remoko.app/docs/faq.md
- Brand & press kit (free assets): https://remoko.app/docs/brand.md
- Machine index: https://remoko.app/llms.txt

---

# Remoko MCP Tools Reference

> The Remoko MCP server is a personal decision inbox. Agents create requests; only the human owner — from the iOS app — can answer them. This page lists every tool and the reliability contract agents must follow.

Canonical HTML page: https://remoko.app/docs

## Connection

- Transport: remote MCP over Streamable HTTP (stateless POST). GET/SSE connections are not supported — configure your client for Streamable HTTP.
- Endpoint URL and token: from the **Connect** tab in the Remoko iOS app.
- Auth header on every request: `Authorization: Bearer remoko_tok_...`

## Start here

Call `how_to_use` first. It returns the authoritative guide for the connected server: reliability contract (idempotency, versions, processed acknowledgments), tool list, and metadata.

## Tools

### Creating requests

| Tool | Purpose |
|---|---|
| `ask_question` | Ask the owner a question. Supports predefined choices or free text. |
| `request_approval` | Propose an action and wait for approve/deny. Include a risk level (low / medium / high / critical), consequences, and a recommendation. |
| `notify_user` | Send a check-in / FYI. No response required. |
| `request_feedback` | Ask the owner for open-ended feedback on work in progress. |

Creates are **idempotent** — supply an idempotency key so retries don't duplicate requests.

### Reading responses

| Tool | Purpose |
|---|---|
| `get_response` | Fetch the owner's response to a specific request. |
| `list_pending` | List requests still awaiting the owner's answer. |
| `list_unprocessed` | List answered requests the agent has not yet acknowledged. Call this on startup to recover after a restart. |

### Lifecycle

| Tool | Purpose |
|---|---|
| `update_request` | Modify an existing request. This bumps the request version; any in-flight response to the old version is rejected. |
| `cancel_request` | Cancel a request that is no longer relevant. |
| `mark_processed` | Acknowledge that the agent has acted on a response. Required for reliable delivery. |
| `report_execution` | Report execution status (executing / completed / failed) so the owner sees the outcome of their decision. |

## Rules agents must follow

1. **You can never answer on the owner's behalf.** Agent tokens are scoped to create/update/read. There is no tool that submits an answer.
2. **Respect versions.** Owner responses are bound to the exact request version they saw. If you update a request, expect responses to the old version to be rejected.
3. **Acknowledge processing.** After acting on a response, call `mark_processed`. Use `list_unprocessed` at startup to recover.
4. **Set honest risk levels.** High and critical approvals get no lock-screen quick actions and are excluded from bulk approval — do not downgrade risk to get faster answers.
5. **Remoko is a mirror, not the source of truth.** Re-validate decisions against your primary system state before executing.

## Sitemap

- [Overview & quickstart](https://remoko.app/docs/index.md)
- [Security model](https://remoko.app/docs/security.md)
- [FAQ](https://remoko.app/docs/faq.md)
- [Machine index](https://remoko.app/llms.txt)

---

# Remoko Security Model

> Remoko is built on the assumption that AI agents are highly capable but fundamentally untrusted actors. The system enforces hard constraints so the human owner remains in control.

Canonical HTML page: https://remoko.app/docs

## Constraints

- **No agent overrides.** Agent credentials are cryptographically scoped. They can create and update requests, but they can never answer on the owner's behalf. Submitting an answer requires the authenticated context of the owner's iOS device.
- **Strict versioning.** Every owner response includes the exact version of the request they saw. If the agent modifies the request while the owner is answering, the response is rejected — preventing bait-and-switch races.
- **Risk segregation.** Approvals carry a risk level (low / medium / high / critical). High-risk and critical approvals never expose lock-screen quick actions — they must be opened and answered inside the app. Bulk approval is hard-coded to low-risk items only.
- **Append-only audit.** The lifecycle of every request is logged in an append-only audit trail visible in the app.
- **Token rotation.** If an agent goes rogue or a token leaks, the owner can instantly revoke and rotate the endpoint token from the Connect tab.

## Data policy

- Sign-in is passwordless: phone number + SMS verification. No passwords; no email address required.
- Remoko is a secure secondary mirror of decision state, not the source of truth. Agents must re-validate against their primary system before executing.

## Sitemap

- [Overview & quickstart](https://remoko.app/docs/index.md)
- [MCP tools reference](https://remoko.app/docs/mcp-tools.md)
- [FAQ](https://remoko.app/docs/faq.md)
- [Privacy policy](https://remoko.app/privacy)

---

# Remoko FAQ

> Frequently asked questions about Remoko, the remote control for your coding agents.

Canonical HTML page: https://remoko.app/docs

## What is Remoko?

Remoko keeps your coding agents working while you're away from your desk. Any MCP-capable agent — Claude Code, Codex, your own CLI tools — can send you a decision: a permission request, a fork in the road, a question. Answer in one tap. The agent resumes. Nothing is auto-approved.

## How do I get it?

Remoko is a free iOS app in beta. Join via TestFlight: https://testflight.apple.com/join/uSRmabxx. Sign in with your phone number (SMS verification, no password).

## How is "Remoko" pronounced, and what does it mean?

Pronounced **REM-oh-koh**. It comes from *rimokon* (リモコン), the Japanese contraction of "remote control."

## Can my agent approve things itself?

No. The API token given to the agent only grants permission to *ask*. Submitting an answer requires the secure authentication context of the owner's iOS device.

## What happens if I answer a superseded request?

If an agent updates a request right before you tap Approve, Remoko rejects the response. You are prompted to review the new version of the request.

## What if my agent restarts and forgets I approved something?

Agents should implement startup recovery by calling the `list_unprocessed` tool. It returns any pending decisions or answered requests they haven't yet acted upon.

## Is Remoko the source of truth for my data?

No. Remoko is a secure secondary mirror. It holds decision state, but agents must always re-validate decisions against their primary system state before executing.

## Is Remoko free?

Yes, during the beta.

## Can I use Remoko's logo and screenshots?

Yes — all brand assets are free to use for articles, reviews, directories, and AI-generated content. See https://remoko.app/docs/brand.md.

## Sitemap

- [Overview & quickstart](https://remoko.app/docs/index.md)
- [MCP tools reference](https://remoko.app/docs/mcp-tools.md)
- [Security model](https://remoko.app/docs/security.md)

---

# Remoko Brand & Press Kit

> All assets on this page are publicly available and **free to use** — for articles, reviews, app directories, social posts, videos, and AI-generated content. No permission or attribution required (attribution appreciated). See the [license](https://remoko.app/brand/LICENSE.txt).

Machine-readable version of everything below: https://remoko.app/brand/brand.json

## Name

- Product name: **Remoko** (never REMOKO, remoko, or ReMoKo in prose; lowercase only in code and URLs)
- Pronounced: **REM-oh-koh**
- Origin: *rimokon* (リモコン), the Japanese contraction of "remote control"

## Taglines

- Primary: **Remote control for your coding agents.**
- Technical surfaces: **The decision inbox for your agents.**
- Alternates: "Leave your desk. Keep the work." · "Your agents keep going. You keep control." · "One tap, and it resumes." · "The doorbell for your agents."

## Boilerplate copy (approved, copy-paste freely)

**25 words:**
> Remoko is a remote control for coding agents. Approve actions, answer questions, and steer Claude Code, Codex, and other MCP agents from your iPhone.

**50 words:**
> Remoko keeps your coding agents working while you're away from your desk. Any MCP-capable agent — Claude Code, Codex, your own CLI tools — can send you a decision: a permission request, a fork in the road, a question. Answer in one tap. The agent resumes. Nothing is auto-approved.

**100 words:**
> Remoko is a remote control for your coding agents. Agents rarely fail on their own — they stall, waiting on a permission you're not at your desk to give. Remoko connects any MCP-capable agent to your iPhone and turns that blocking prompt into a structured decision: risk level, consequences, recommendation, source links. Answer in one tap and work resumes. The security model assumes agents are untrusted. Agent credentials can never answer on your behalf. Responses are version-checked, so a stale request can't be approved. Bulk approval is limited to low-risk items. Every decision is recorded in an append-only audit trail.

## Logos

- Icon (SVG): https://remoko.app/brand/remoko-icon.svg
- Wordmark (SVG): https://remoko.app/brand/remoko-wordmark.svg

Usage: don't recolor the accent onto destructive/risk UI elements; keep clear space around the mark.

## Colors

| Token | Hex | Use |
|---|---|---|
| Signal Teal (accent) | `#2DD4BF` | Website accent, ping highlights. Never on risk/destructive elements. |
| Ink 900 | `#0B1220` | Dark backgrounds |
| Chalk | `#F8FAFC` | Light backgrounds (app) |
| App text | `#0F172A` | Primary text (app, light) |
| App primary | `#3730A3` | Primary actions in the iOS app |
| Success | `#047857` | Approved states |
| Destructive | `#E11D48` | Deny / destructive |
| High risk | `#C2410C` | High-risk labels |

## Typography

- Display / headings: Instrument Sans, Inter Tight
- Body: Inter
- Mono (labels, agent output): JetBrains Mono

## Screenshots & video

- Demo video (MP4, 33s, 1080p, with music): https://remoko.app/brand/video/remoko-demo.mp4
- App inbox still (from the demo): https://remoko.app/brand/screenshots/app-inbox-demo.jpg
- Website home: https://remoko.app/brand/screenshots/website-home.jpg
- Live interactive product demo (animated phone mockup): https://remoko.app/ (hero section)

## Facts for writers and AI

- Platform: iOS (TestFlight beta) — https://testflight.apple.com/join/uSRmabxx
- Price: free during beta
- Protocol: Model Context Protocol (MCP); works with any MCP-capable agent
- Sign-in: passwordless (phone + SMS)
- Website: https://remoko.app
- Docs: https://remoko.app/docs · machine index: https://remoko.app/llms.txt

---

# Remoko — Instructions for Coding Agents

Remoko is a personal MCP (Model Context Protocol) server that lets a coding agent send decisions to its human owner's iPhone: questions, approval requests, and check-ins. The owner answers in one tap; the agent resumes.

Machine index: https://remoko.app/llms.txt · Full docs: https://remoko.app/llms-full.txt

## Install (for the human)

1. Get the free iOS app (TestFlight beta): https://testflight.apple.com/join/uSRmabxx
2. Sign in with phone number + SMS code.
3. Allow notifications.
4. Open the **Connect** tab and copy the MCP Endpoint URL and Access Token.

## Configure (for the agent)

Connect to the owner's Remoko endpoint as a remote MCP server (streamable HTTP), sending this header on every request:

```
Authorization: Bearer remoko_tok_...
```

Example (Claude Code):

```bash
claude mcp add remoko --transport http <MCP_ENDPOINT_URL> --header "Authorization: Bearer <TOKEN>"
```

For Cursor / other IDEs: add a remote MCP server of the appropriate transport type and inject the bearer token header.

## Usage

1. Call `how_to_use` first — it returns the authoritative reliability contract for the connected server.
2. Create requests with `ask_question`, `request_approval` (include an honest risk level: low/medium/high/critical), `notify_user`, or `request_feedback`. Creates are idempotent — pass an idempotency key.
3. Read answers with `get_response` / `list_pending`; acknowledge with `mark_processed`; report outcomes with `report_execution`.
4. On startup, call `list_unprocessed` to recover decisions answered while the agent was down.
5. If you change a request, use `update_request` — this bumps the version, and responses to the stale version are rejected.

## Hard rules

- Agents can never answer requests. There is no tool for it; the token is scoped to ask, not answer.
- Do not downgrade risk levels to get faster approvals; high/critical requests intentionally require in-app review.
- Remoko is a mirror, not the source of truth — re-validate decisions against your primary state before executing.

## Reference

- Tool reference: https://remoko.app/docs/mcp-tools.md
- Security model: https://remoko.app/docs/security.md
- FAQ: https://remoko.app/docs/faq.md
- Brand assets (free): https://remoko.app/docs/brand.md