yaver.io

# Yaver

[![Tests](https://github.com/kivanccakmak/yaver.io/actions/workflows/test-suite.yml/badge.svg)](https://github.com/kivanccakmak/yaver.io/actions/workflows/test-suite.yml)
[![License: FSL-1.1-Apache-2.0](https://img.shields.io/badge/License-FSL--1.1--Apache--2.0-blue.svg)](LICENSING.md)

Docs: [CI setup](CI.md) · [Test SDK](docs/yaver-test-sdk.md) · [Runtime Control Plane](docs/runtime-control-plane.md)

**Build apps and game loops from your phone. Keep the backend and build machine local until you decide otherwise.**

> **Using an AI agent?** If a coding agent (Claude Code, Codex, Cursor, Aider, …) is reading this
> because the human asked it to *"install yaver"* or *"set up yaver"*, stop here and
> fetch **[https://yaver.io/llms.txt](https://yaver.io/llms.txt)** — that file is the
> canonical, machine-readable install + configure guide. It covers headless / WSL / SSH,
> the resumable device-code flow, and exactly what to surface back to the human. Do not
> scrape the rest of this README as a substitute.


Yaver's short-term product target is phone-first app and backend creation, then promotion to your own dev machine, then optional promotion to Yaver Cloud. The core claim is narrow on purpose:

`phone sandbox -> your dev machine -> Yaver Cloud`

What is real in the repo today:

- Hermes reload from Linux, WSL, macOS, or a remote host into the Yaver mobile app
- local phone-project sandboxing with SQLite-backed data, schema, auth personas, seed data, and CRUD
- portable export/import/push of a phone project to another `yaver serve` agent
- remote dev-box flows where the box is mostly web UI + backend, runs Claude Code / Codex / other coding agents, and streams run/test output back to mobile
- MCP and CLI surfaces for phone project export, import, and push
- local-first runtime API for third-party apps using per-project tokens
- npm-based install and upgrade via `npm install -g yaver-cli` across macOS, Linux, and WSL
- Unity feedback/build/test/relaunch groundwork for mobile and desktop projects

What is still incomplete:

- the default one-tap monorepo scaffold for phone-created projects
- more polish on the AI prompt-to-project scaffold
- a fully proven end-to-end App Store / TestFlight release loop from this machine

## The Clear Story

Yaver's primary loop is:

1. Start on the phone.
2. Vibe-code the app and backend from the phone.
3. Run the first backend tier in the phone sandbox.
4. Grow the same project onto your dev machine, your own server, or Yaver Cloud.
5. Keep Supabase, Convex, Postgres, Turso, Firebase, and similar systems as escape hatches, not the default destination.

What is first-class today:

- **Hermes reload from Linux / WSL / remote host to iPhone or Android** through the Yaver mobile app
- **Mobile-first backend sandbox** with schema, auth personas, seed data, CRUD, and local persistence
- **Promotion to your own hardware** via `yaver serve` on a Mac, Linux box, Pi, VPS, or other reachable machine
- **Remote coding-box workflows** where your machine is just the app/backend box, Yaver runs the app or tests there, and the phone watches the live stream
- **Promotion to Yaver Cloud** via the same portable bundle and the same `yaver serve` binary
- **Containerized export** for running the promoted backend on your own cloud with Docker
- **Escape routes** to systems like Supabase and Convex as secondary trust signals

What is not fully finished yet:

- **Phone-first monorepo scaffolding** as the default one-tap `init` path
- **Prompt scaffold quality polish** for the phone-created full-stack starter

The headline path is Yaver-native:

`phone sandbox -> your dev machine / your cloud / Yaver Cloud`

Everything else is there so the user knows they can leave later.

For a WSL-based developer, that means:

1. Run `yaver serve` or the Go agent tooling on WSL/Linux.
2. Build the Hermes bundle on that host.
3. Open the app inside the Yaver mobile app on the phone.
4. Use native-install paths only when you actually need a full store/native build.

## The Three Pieces of Yaver

Yaver is built for solo developers and small teams who ship from anywhere. It has three distinct pieces:

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                                                                             │
│  📱 MOBILE APP (yaver.io)                    🔧 AGENT (yaver)              │
│  App Store / Play Store                       npm install -g yaver-cli      │
│                                                                             │
│  Remote control for everything.              The brain on your dev machine. │
│  Send tasks to AI agents, test apps on       Runs AI agents (Claude Code,   │
│  real hardware, hot reload, visual QA.       Codex, Aider). Serves P2P      │
│  Native container for RN apps (not WebView). connections, manages builds,   │
│  Works from beach, coffee shop, anywhere.    pushes RN bundles to phones,   │
│                                              MCP server with 473 tools.     │
│                                                                             │
│  ─────────────────────────────────────────────────────────────────────────  │
│                                                                             │
│  🐛 FEEDBACK SDK                                                            │
│  yaver feedback setup                                                       │
│                                                                             │
│  Embed in YOUR app during dev. Shake to report bugs with screenshots +      │
│  voice. Black box flight recorder streams all events to your AI agent.      │
│  React Native, Flutter, Web.                                                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

**You might use:**
- Just the **mobile app + agent** — control AI agents from your phone, hot reload any framework
- Add the **Feedback SDK** — embed a debug console in your app, shake to report bugs to your AI agent. If you pair a guest app with Yaver, let the Feedback SDK own haptics; do not keep a second app-level `expo-haptics` layer active on top.
- All three together — the full loop: code on machine, push to device, test, report bugs, AI fixes, repeat

## Yaver Protocol v1 — never feel disconnected

The agent is the **producer**; the mobile app and dashboard are **consumers**. They communicate over an SSE channel at `/dev/events` using a structured protocol with three guarantees:

1. **Real progress, not fake.** The agent regex-parses Metro / Expo / Hermesc stdout (`Bundling 67% (1247/2390)`) into structured `progress` events with `pct`, `done`, `total`, `currentFile`, `etaMs`, and a `progressSrc` of `exact` / `heuristic` / `unknown`. Consumer renders an indeterminate spinner for `unknown`; never fakes a percentage.
2. **Snapshots every 5 seconds.** `snapshot` events embed the full picture: every active topic's phase, last progress, recent log tail. A reconnecting consumer reads ONE snapshot and is fully caught up.
3. **Liveness contract decoupled from compile state.** Consumer tracks time-since-last-byte separately from compile progress. `< 6s = live · 6–15s = syncing · 15–60s = reconnecting · > 60s = lost`. Slow compiles never look like "lost" connections.

Topics: `dev/start` · `webview/build` · `hermes/compile` · `bundle/push`. Phases per topic and full event schema in [`docs/yaver-protocol.md`](docs/yaver-protocol.md).

## AI + IoT Fix Architecture

Yaver is also the control-plane shape for an AI-driven IoT repair loop.

The architecture we are designing is:

`mobile orchestrator -> cloud brain -> LLM coordinator -> c-agent runtime on device`

The simple version is:

`LLM writes code -> toolchain compiles it -> firmware already has c-agent -> device dynamically loads/runs it -> result comes back -> loop iterates`

Each layer has one job:

- **Mobile orchestrator**: operator UI, incident intake, approvals, live status
- **Cloud brain**: session coordination, audit trail, retrieval, module registry, signing pipeline
- **LLM coordinator**: decides which probe or fix should run next for this incident
- **c-agent runtime**: small device-side runtime that verifies artifacts, binds capabilities, executes bounded code, and streams results back

The important distinction is that the LLM is not the runtime. The model writes the next probe or fix. The runtime is what makes that code actually runnable on the device.

That matters for real IoT repair cases. A Klipper printer, OpenWrt router, PX4 drone, or robotics host rarely fails in a way that a static predefined tool list fully covers. The useful system is one that can author a small incident-specific probe or fix, compile it, ship it, run it safely on the device, inspect the result, and iterate.

An important hardware/firmware design rule falls out of that: AI-fixable components should be able to enter a bounded stuck or degraded mode instead of crashing the whole device. If a dependency wedges, the component should quiesce, preserve enough state, report that it is waiting for replacement, and resume when a new module is inserted and validated. Good firmware architecture is mandatory. That is the difference between a system the brain can iteratively repair and a system that just hard-resets on every subsystem fault.

That loop looks like:

`phone reports issue -> brain plans -> LLM writes bounded probe/fix -> build/sign -> c-agent verifies/runs -> telemetry returns -> LLM writes next attempt -> repeat until fixed or budget hit`

This is the motivation behind the `embedded/c-agent/` work in this repo and the architecture docs under `docs/c-agent-*.md`.

## Key Features

- **Push to Device** — Real-device testing in ~4 seconds. No TestFlight. 40+ native modules.
- **Visual QA Loop** — Shake to report. AI sees screenshot, writes fi