# 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