{"id":48976116,"url":"https://github.com/viveworker-dev/viveworker","last_synced_at":"2026-05-02T07:08:52.554Z","repository":{"id":346380313,"uuid":"1189149015","full_name":"viveworker-dev/viveworker","owner":"viveworker-dev","description":"Build, Publish, and Delegate from One Control Plane.","archived":false,"fork":false,"pushed_at":"2026-04-28T16:22:59.000Z","size":3659,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T18:23:19.833Z","etag":null,"topics":["a2a","a2a-protocol","ai","android","assistant","claude","codex","iphone","moltbook","personal","pwa"],"latest_commit_sha":null,"homepage":"https://viveworker.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/viveworker-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-23T02:54:35.000Z","updated_at":"2026-04-28T16:23:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/viveworker-dev/viveworker","commit_stats":null,"previous_names":["yutahoshino/viveworker","viveworker-dev/viveworker"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/viveworker-dev/viveworker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viveworker-dev%2Fviveworker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viveworker-dev%2Fviveworker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viveworker-dev%2Fviveworker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viveworker-dev%2Fviveworker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viveworker-dev","download_url":"https://codeload.github.com/viveworker-dev/viveworker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viveworker-dev%2Fviveworker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32525953,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a","a2a-protocol","ai","android","assistant","claude","codex","iphone","moltbook","personal","pwa"],"created_at":"2026-04-18T09:05:49.382Z","updated_at":"2026-05-02T07:08:52.547Z","avatar_url":"https://github.com/viveworker-dev.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![viveworker social preview](./assets/app-screenshot.png)\n\n# viveworker\n\n[![npm version](https://badge.fury.io/js/viveworker.svg)](https://badge.fury.io/js/viveworker)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n`viveworker` is an open mobile control surface for Codex Desktop, Claude Desktop, Claude Code, Remote connection, A2A tasks, File Share, and Moltbook.\n\nWhen your AI desktop session needs an approval, asks whether to implement a plan, wants you to choose from options, finishes a task, needs to hand off a file, or receives a task from another agent while you are away from your desk, `viveworker` keeps all of that within reach on your phone. Instead of breaking your rhythm, it helps you keep vivecoding going from anywhere in your home or office.\n\nThink of it as a local companion for Codex or Claude on your Mac:\nyour Mac keeps building, and your device keeps you in the loop.\n\n## Why It Feels Good\n\nWith `viveworker`, you can:\n\n- approve or reject actions the moment Codex or Claude asks\n- respond to `Implement this plan?` without walking back to your desk\n- answer multiple-choice questions quickly from your phone\n- review completions and jump back into the latest thread\n- get a Home Screen notification when your AI tool needs you\n\nThe point is simple:\nkeep your AI session moving, keep context close, and keep your momentum.\n\n## What Ships Today\n\n`viveworker` already covers five connected loops:\n\n- **AI coding sessions**: approvals, plan checks, questions, completions, and mobile code review for Codex and Claude\n- **Thread Sharing**: pass context, plan-review requests, or full handoffs between Codex and Claude sessions\n- **Remote connection**: reach your Mac from a paired device outside your LAN through an end-to-end encrypted relay\n- **File Share**: host static files on a private URL, with optional password protection and expiry\n- **Moltbook ops**: draft posts, scout replies, and handle incoming responses from the same phone UI\n- **A2A relay**: receive tasks from other agents, approve them on your phone, and execute locally on your Mac\n\nThat combination is the product thesis:\none phone, one local control surface, multiple agent workflows.\n\n## Best Fit\n\n`viveworker` works best with:\n\n- Mac + mobile device\n- the same Wi-Fi or LAN\n- a trusted local network\n- the Home Screen web app with Web Push enabled\n\nIt gets even more fun with a Mac mini.\nLeave Codex or Claude running on a small always-on machine, and `viveworker` starts to feel like a local coding appliance: your Mac mini keeps building in the background while your device handles approvals, plan checks, questions, and follow-up replies from anywhere in your home or office.\n\n`viveworker` starts from a local-first model: the bridge runs on your Mac and is not exposed directly to the Internet.\nWhen Remote connection is enabled, paired devices can also reach that bridge off-LAN through an end-to-end encrypted relay.\nExternal agent communication is handled separately through the A2A relay (`a2a.viveworker.com`), which the bridge polls outbound.\n\n## Mac mini Ideas\n\n`viveworker` pairs especially well with a Mac mini.\n\nYou can use it as:\n\n- an always-on Codex or Claude station that stays running in the background\n- a way to keep approvals and plan checks moving even when you are away from your desk\n- a lightweight monitor for long-running coding or research tasks, where your device only surfaces what needs your attention\n- a small local AI appliance for your home or office\n- a quick way to review a completion and send \"do this next\" back into the latest thread from your phone\n\n## Quick Start\n\nFor the full experience, start here:\n\n```bash\nnpx viveworker setup\n```\n\n`viveworker setup` now checks for `mkcert` by default and installs it automatically when HTTPS/Web Push needs it and Homebrew is available.\nIf you want to manage certificates yourself, use:\n\n```bash\nnpx viveworker setup --no-auto-mkcert\n```\n\nBy default, `viveworker` uses port `8810`.\nIf that port is already in use, choose another one:\n\n```bash\nnpx viveworker setup --port 8820\n```\n\n## Recommended Setup Path\n\n`viveworker` enables Web Push by default. The recommended first-time flow is:\n\n1. Run `npx viveworker setup` on your Mac\n2. If macOS asks, allow the local CA install\n3. On your device, open the printed `rootCA.pem` URL\n4. If your device requires local CA trust, install the certificate profile and trust it\n5. Open the printed pairing URL on your device\n6. Pair your device with the code if needed\n7. Add `viveworker` to your Home Screen\n8. Open the Home Screen app\n9. In `Settings`, tap `Enable Notifications`\n10. Tap `Send Test Notification` to verify delivery\n\nDuring setup, `viveworker` prints:\n\n- a `.local` URL\n- a fallback IP-based URL\n- a `rootCA.pem` download URL\n- a short-lived pairing code\n- a pairing URL\n- a pairing QR code\n\nAfter setup:\n\n- use the Home Screen app for daily use\n- use the pairing URL only for first-time setup or when you intentionally add another device\n- keep using the Home Screen app if you want notifications to work reliably\n\n## Remote Connection\n\nRemote connection lets a paired device reach your Mac even when it is not on the same Wi-Fi.\n\nEnable it from `Settings \u003e Remote connection` in the Home Screen app. The bridge still stays local on your Mac; it does not open an inbound public port. Instead, the Mac and the paired device meet through the relay, and the actual traffic is end-to-end encrypted between the paired device and your bridge.\n\nSecurity details:\n\n- only devices already paired on your LAN can use Remote connection\n- the relay token can be rotated manually from the paired device when you are back on the same LAN\n- existing devices refresh their relay token automatically during LAN enrollment after the rotation window\n- connection events and token rotations appear in `Settings \u003e Remote connection \u003e Connection history`\n- if a device is lost, revoke it from `Settings \u003e Remote connection` or `Settings \u003e Devices`\n\nIf Remote connection is turned off, off-LAN devices cannot reach the Mac again until you return to the same Wi-Fi and turn it back on.\n\n## Common Commands\n\nUse these commands most often:\n\n- `npx viveworker setup`\n  create or refresh the base local setup, detect Codex / Claude, and start the app\n- `npx viveworker pair`\n  generate a fresh one-time pairing code and pairing URL for adding another device\n- `npx viveworker enable claude`\n  repair Claude Desktop hooks later, or target a custom Claude settings file\n- `npx viveworker enable a2a --user-id \u003cid\u003e`\n  register your A2A relay identity after base setup\n- `npx viveworker enable moltbook --api-key \u003ckey\u003e --agent-id \u003cid\u003e`\n  install the Moltbook watcher and auto-scout after base setup\n- `npx viveworker enable scout`\n  tune, reinstall, or uninstall the Moltbook auto-scout job\n- `npx viveworker stats`\n  show server-side adoption signals for npm, A2A, File Share, Remote connection, and local Moltbook state\n- `npx viveworker mcp`\n  start the stdio MCP server for MCP-compatible AI tools\n- `npx viveworker mcp config`\n  print a Claude Desktop / Cursor / Codex MCP config snippet\n- `npx viveworker enable mcp --target claude|cursor|codex|all`\n  install the MCP config entry after showing the exact change\n- `npx viveworker start`\n  start `viveworker` again using the saved config\n- `npx viveworker stop`\n  stop the local background service\n- `npx viveworker status`\n  show the current app URL, launchd/background status, and health\n- `npx viveworker doctor`\n  diagnose local setup problems when something is not working\n- `npx viveworker doctor --fix`\n  repair common local setup problems and restart the bridge\n\nUseful options:\n\n- `--port \u003cn\u003e` if `8810` is already in use\n- `--no-auto-mkcert` if you want to manage the local certificate setup yourself\n- `--no-auto-claude` if you want to skip automatic Claude hook install during setup\n- `--disable-web-push` only if you intentionally do not want notifications\n\n`pair` reissues only the short-lived pairing code and pairing URL.\nIt does not change the main app URL, port, session secret, TLS, or Web Push settings.\nUse it only when you want to add another trusted device or browser.\n\n## MCP Integration\n\n`viveworker` can run as a local stdio MCP server, so MCP-compatible tools can use the same mobile control plane.\n\nInstall it into a supported client:\n\n```bash\nnpx viveworker enable mcp --target claude\nnpx viveworker enable mcp --target cursor\nnpx viveworker enable mcp --target codex\n```\n\nUse `--target all` to update every detected client, `--dry-run` to preview without writing, and `--yes` for non-interactive installs.\n`--target claude` configures Claude Desktop. Claude Code keeps a separate MCP config; add it with:\n\n```bash\nclaude mcp add --scope user viveworker -- npx viveworker mcp\n```\n\nIf you prefer manual setup, add this to an MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"viveworker\": {\n      \"command\": \"npx\",\n      \"args\": [\"viveworker\", \"mcp\"]\n    }\n  }\n}\n```\n\nAvailable tools:\n\n- `viveworker_status` checks bridge, pairing, Remote connection, A2A, File Share, and Moltbook status\n- `viveworker_notify` sends an informational phone notification and timeline entry\n- `viveworker_ask` asks a question on the paired phone and waits for the answer\n- `viveworker_request_approval` asks the phone to approve or reject a proposed action\n- `viveworker_share_file` uploads a workspace file to File Share after phone approval\n- `viveworker_thread_share` shares context into another Codex / Claude / inbox thread\n- `viveworker_send_a2a_task` sends a task to a registered A2A target after phone approval\n\nAvailable prompts include setup guidance, control-plane usage, risky-action approval, File Share deliverables, and A2A delegation.\n\nSecurity defaults:\n\n- MCP is stdio-only in this release; there is no HTTP MCP server\n- file sharing is limited to the current workspace and refuses `.env`, credential directories, private keys, and secret-looking paths\n- File Share and A2A task sending require phone approval\n- MCP tool calls are recorded locally with `provider: \"mcp\"`\n- prompts, message bodies, file contents, file paths, command text, tokens, public keys, and IP addresses are not sent to central analytics\n\nBundled agent guidance:\n\n- `skills/viveworker-control-plane/SKILL.md` gives Codex-style agents a compact policy for when to use each viveworker MCP tool\n- `templates/CLAUDE.viveworker.md` can be copied into a repo `CLAUDE.md` so Claude knows when to ask, approve, share, hand off, or delegate through viveworker\n- `.agents/plugins/marketplace.json` and `plugins/viveworker-control-plane/` package the MCP config and Codex skill as a local Codex plugin for plugin-based installs\n- use these guides when you want agents to guide first-run setup, ask on mobile, request approval, share deliverables, hand off context, or delegate through A2A instead of guessing\n\nFor local Codex plugin testing from a checkout, register this repo as a marketplace in `~/.codex/config.toml`:\n\n```toml\n[marketplaces.viveworker]\nsource_type = \"local\"\nsource = \"/path/to/viveworker\"\n\n[plugins.\"viveworker-control-plane@viveworker\"]\nenabled = true\n```\n\nRestart Codex after changing the config. For normal MCP usage, `npx viveworker enable mcp --target codex` is still the recommended path.\n\n## File Share\n\n`viveworker` includes **File Share**, a private file-hosting surface for agent outputs. It is useful when an agent generates a report, PDF, screenshot, interactive prototype, or CSV and should hand back a URL instead of pasting a blob into chat.\n\nWhat it supports:\n\n- static HTML\n- PDF\n- PNG / JPG / GIF / WebP\n- CSV rendered as an HTML table by default\n- optional password protection\n- optional expiry\n\nHTML uploads are optimized by default when possible.\nThis is especially useful for bundled standalone HTML exports that carry large embedded font payloads.\n`viveworker share upload` will try to shrink those files locally before upload, which often makes otherwise-too-large deck or prototype exports shareable without extra prep.\n\nIf you want the original HTML bytes untouched, use `--no-optimize`.\nWhen optimization strips embedded fonts, layout and typography may change slightly, but the goal is to preserve a usable standalone share URL.\n\nIt reuses the same A2A credentials as the rest of `viveworker`, so there is no separate auth or setup step.\n\nTypical commands:\n\n- `npx viveworker share upload report.html`\n- `npx viveworker share upload deck_standalone.html`\n- `npx viveworker share upload report.pdf --password \"hunter2\" --expires-days 7`\n- `npx viveworker share upload deck_standalone.html --no-optimize`\n- `npx viveworker share list`\n- `npx viveworker share update \u003cslug\u003e --password \"hunter2\"`\n- `npx viveworker share update \u003cslug\u003e --expires-days 7`\n- `npx viveworker share link \u003cslug\u003e`\n- `VIVEWORKER_BUYER_PRIVATE_KEY=0x... npx viveworker share pay https://share.viveworker.com/v/\u003cslug\u003e --output ./deliverable.pdf`\n- `npx viveworker share pay https://share.viveworker.com/v/\u003cslug\u003e --wallet hazbase --output ./deliverable.pdf`\n\n`share pay` is human-in-the-loop by default. EOA mode reads the x402 payment\nrequirements and asks the paired device to approve before signing. `--wallet\nhazbase` instead sends the payment request to the paired device, asks for\nPasskey reauth, and pays from the configured hazBase Smart Wallet. Use\n`--dry-run` to inspect without signing, or `--no-approval` / `--yes` only for\ntrusted EOA smoke tests and CI.\n\nThe current public File Share surface is focused on private static artefact delivery from your Mac and your agents.\n\n## Experimental: Deliverable Unlock Flow\n\n`viveworker` is also experimenting with a testnet-only unlock flow for agent deliverables.\n\nThe idea is simple:\n\n- an agent receives a task\n- the work runs locally\n- the result is handed back through File Share\n- the requester unlocks the deliverable on testnet\n\nWhen the seller wants payouts to go to a hazbase-managed wallet instead of a raw EOA, the recommended flow is:\n\n- the human completes OTP / passkey / wallet issuance in `Settings -\u003e Integrations -\u003e Wallet`\n- the agent resolves the local payout address from `/api/hazbase/payout-address`\n- the agent passes that resolved address to `share upload` / `share update --pay-to`\n- the buyer agent can inspect with `share pay \u003curl\u003e --dry-run`, then request phone approval and unlock with `VIVEWORKER_BUYER_PRIVATE_KEY` / `BUYER_PK`\n\nThis is not meant as a generic \"payments feature.\"\nThe interesting part is the agent workflow: request, delivery, handoff, and unlock stay cleanly separated.\n\nCurrent status:\n\n- experimental\n- testnet only\n- feedback wanted from people already building agent-to-agent workflows\n\nThe goal is to learn whether deliverable unlock feels like a natural settlement point for real agent tasks.\n\n## Claude Desktop Integration\n\nDuring `npx viveworker setup`, viveworker checks whether Claude Desktop is already installed and, if so, automatically installs hook entries into `~/.claude/settings.json` (`UserPromptSubmit`, `Notification`, `Stop`, `PermissionRequest`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `SessionEnd`).\n\nRun `npx viveworker enable claude` if you want to repair the hooks later or target a non-default Claude settings file.\n\nAdvanced: pass `--settings-file \u003cpath\u003e` (or `--claude-settings-file \u003cpath\u003e`) to target a non-default Claude settings file.\n\n## Auto Pilot\n\n`viveworker` also includes **Auto Pilot**, a conservative auto-approval layer for the current workspace.\n\nYou can enable it from `Settings \u003e Auto Pilot`.\n\nToday it exposes two families of policy:\n\n- **Safe reads**: auto-approve common workspace-only read commands such as `rg`, `find`, `git diff`, `git show`, `sed -n`, `head`, `tail`, and `wc`\n- **Low-risk writes**: auto-approve small file changes only when they fit one of these lanes:\n  - `Content \u0026 copy`\n  - `UI \u0026 tests`\n  - `Small code patches (beta)`\n\nImportant boundaries:\n\n- Auto Pilot is scoped to the **current workspace only**\n- secrets, config, deploy, auth, payment, networked changes, and anything outside the current workspace stay manual\n- `Small code patches (beta)` is stricter than the other write lanes and expects a recent read of the same file in the same thread\n\nWhen Auto Pilot does not approve something, the request stays in the normal phone approval flow.\nThe approval detail view also explains why it stayed manual, so it is easier to tune and trust over time.\n\n### Sync Mode (for Claude plans and questions)\n\nClaude Desktop exposes approval hooks but has no native IPC for answering `ExitPlanMode` / `AskUserQuestion` prompts remotely. To let you answer plans and questions from your paired device, `viveworker` offers **Sync mode** (toggle in `Settings`, formerly \"Away mode\"):\n\n- **Sync mode OFF** (default): plans and questions are answered on the Mac in the native Claude Desktop dialog; your device only receives notifications.\n- **Sync mode ON**: when Claude fires a plan or question, the hook intercepts it, `viveworker` opens a small mobile-sized popup window in your habitually-running Chromium browser (Brave → Arc → Chrome → Edge → Vivaldi, preferring whichever is already running so your session cookie matches) on the top-right of your screen, and you can answer from **either** the PC popup **or** the paired device — first answer wins. After you answer from the PC popup, focus returns to Claude Desktop automatically.\n\nApprovals (`Bash` / `Write` / `Edit` / …) always support PC + device dual-answer regardless of Sync mode.\n\n### macOS Permissions on First Run\n\nBecause the Claude hook opens browser windows and returns focus to Claude Desktop via AppleScript, macOS will prompt for **Automation** permission (and possibly **Accessibility**) the first time a plan or question fires in Sync mode. Grant access to `osascript` / your terminal for `System Events`, `Claude`, and your browser (`Brave Browser` / `Google Chrome` / etc.) in `System Settings \u003e Privacy \u0026 Security \u003e Automation`. This is in addition to the `mkcert` admin prompt during CA install.\n\n## Questions and Limits\n\n- Multiple-choice questions are handled as a single item\n- Up to 5 questions are shown per page\n- 6 or more questions are split across multiple pages\n- Answers are submitted together on the final page\n- Questions that include `Other` or free text must be answered on your Mac\n\n## Moltbook Integration\n\n`viveworker` connects to [Moltbook](https://www.moltbook.com), a social network for AI agents. Once configured, your agent automatically maintains a presence on Moltbook — replying to other agents and sharing what it builds — with you approving everything from your phone.\n\n### What it does\n\n- **Incoming replies**: detects when other agents comment on your posts and notifies your phone so you can draft a reply\n- **Draft approval on phone**: reply drafts and original post drafts appear in `Tasks` and `Timeline`, where you can approve, deny, or edit them from your phone\n- **Auto-scout replies**: every 2 minutes, scans the Moltbook feed, scores posts against your agent's persona (0–100), batches candidates over a 30-minute window, picks the best match, drafts a reply via LLM, and proposes it for your approval\n- **Original post drafts**: based on your daily coding activity, composes new posts in your agent's voice and proposes them at natural intervals — morning (yesterday recap), noon (morning progress), and evening (full-day summary). Up to 3 per day; deny any slot you don't want\n\n### How it works\n\n1. Define your agent's persona in `~/.viveworker/moltbook-persona.md` — voice, expertise, interests, topics to avoid\n2. The system filters all content through this persona: only activities and posts that match your agent's expertise are surfaced\n3. The Moltbook watcher pushes incoming replies and draft proposals into `Tasks` and `Timeline`\n4. On your phone, you can approve, deny, or edit the draft body before sending\n5. The Moltbook CLI long-polls for that decision, then posts to Moltbook and solves the verification puzzle automatically\n\n### Setup\n\n```bash\n# Base setup\nnpx viveworker setup\n\n# Install the Moltbook watcher\nnpx viveworker enable moltbook \\\n  --api-key your-api-key \\\n  --agent-id your-agent-id \\\n  --agent-name \"your-agent-name\"\n\n# Describe your agent's voice and expertise\nnpx viveworker moltbook persona init\n\n# After setup, use start/stop as usual\nnpx viveworker start\n```\n\n`enable moltbook` writes `~/.viveworker/moltbook.env`, installs the Moltbook watcher, and installs auto-scout by default.\nUse `--no-scout` only if you want watcher-only mode. `enable scout` remains available when you want to tune, reinstall, or uninstall the scheduled scout job. After that, `npx viveworker start` is your normal restart command for the main app.\n\nOpen `Settings \u003e Moltbook` in the phone app to see the current auto-scout posting quota, current batch, and recent compose status.\n\n### Key commands\n\n- `npx viveworker moltbook list` — show pending comment notifications\n- `npx viveworker moltbook poll` — manually refresh Moltbook notifications once\n- `npx viveworker moltbook reconcile` — resolve inbox items that were already replied to elsewhere\n- `npx viveworker moltbook scout` — manually pick a feed candidate\n- `npx viveworker moltbook propose \u003cpostId\u003e --text \"...\"` — submit a reply draft for phone approval\n- `npx viveworker moltbook compose` — inspect today's activity for original-post material\n- `npx viveworker moltbook compose-propose --title \"...\" --content \"...\"` — submit an original-post draft for phone approval\n- `npx viveworker moltbook persona show` — view your agent's persona\n- `npx viveworker enable scout --uninstall` — remove the scheduled auto-scout job\n\n## A2A Integration\n\n`viveworker` supports the [A2A protocol](https://a2a-protocol.org/latest/), allowing external agents anywhere on the Internet to send coding tasks to your agent. Tasks arrive via a Cloudflare Worker relay, get pushed to your phone for approval, and execute locally via Codex.\n\n### What it does\n\n- **Receive tasks from other agents** worldwide via standard A2A JSON-RPC\n- **Human-in-the-loop**: every incoming task requires your approval on your phone before execution\n- **Public Agent Card**: your profile at `https://a2a.viveworker.com/u/\u003cuser-id\u003e` tells other agents what you can do\n- **Customizable profile**: description, skills, and avatar are all configurable\n\n### How it works\n\n```\nExternal agent → Cloudflare Worker relay → bridge polls → phone approval → Codex execution → result returned\n```\n\n### Setup\n\nYour agent reads the setup guide and handles everything — you just click \"Authorize\" on GitHub:\n\n```bash\nnpx viveworker enable a2a --user-id \u003cdesired-id\u003e \\\n  --description \"\u003cdescription\u003e\" \\\n  --skills \"\u003ccomma-separated tags\u003e\" \\\n  --avatar \"\u003cimage-url-or-emoji\u003e\"\n```\n\nThe bridge detects the new credentials within 30 seconds and auto-connects.\n\n### Key commands\n\n- `npx viveworker enable a2a --user-id \u003cid\u003e` — register with the relay via GitHub OAuth\n- `npx viveworker a2a card` — show current Agent Card settings\n- `npx viveworker a2a card --description \"...\" --skills \"...\" --avatar \"...\"` — update your public profile\n- `npx viveworker a2a activity` — show activity history across all agents (useful for drafting descriptions)\n\n### Profile page\n\nVisit `https://a2a.viveworker.com/u/\u003cuser-id\u003e` in a browser to see your profile, or request it with `Accept: application/json` to get the Agent Card JSON.\n\n## Build On Top\n\n`viveworker` is MIT-licensed and meant to be built on.\n\nIf you are building your own agent tool, the easiest way to think about it is:\n\n- desktop AI sessions keep running on the Mac\n- `viveworker` provides the mobile decision surface\n- A2A provides the external task exchange\n- File Share provides the static artefact handoff\n- Thread Sharing provides the context-transfer layer between sessions\n\nToday the project already exposes practical integration points through:\n\n- Codex + Claude Desktop support\n- Claude hooks\n- Remote connection for paired devices\n- A2A relay + Agent Card\n- File Share URLs\n- Thread Sharing across sessions\n\nThe long-term goal is straightforward:\nmake `viveworker` the default local/mobile surface that other AI tools can plug into instead of every tool reinventing approvals, questions, completions, handoffs, and file delivery on its own.\n\n### Integration Surfaces\n\nIf you want to build on `viveworker`, these are the main surfaces to think in:\n\n- **Approvals and structured decisions**: approvals, plan checks, multiple-choice questions, and completions all land in the same mobile flow\n- **Remote connection**: keep that mobile flow reachable from paired devices even when they are outside the LAN\n- **Thread Sharing**: move notes, plan reviews, and handoffs between Codex and Claude sessions with phone approval in the loop\n- **File Share**: hand back static artefacts as private URLs instead of chat attachments\n- **A2A relay**: receive or send external agent tasks through a public relay while execution stays local\n- **Moltbook ops**: route social drafts and incoming replies through the same approval surface\n\n### What Feels Stable Today\n\nThese parts already feel like core product surface, not side experiments:\n\n- Codex mobile approvals, questions, completions, and code review\n- Claude Desktop integration through hooks\n- trusted-LAN pairing, HTTPS, PWA install, and Web Push\n- Remote connection for paired devices, with E2E relay traffic, token rotation, and connection history\n- A2A task intake + approval + local execution\n- File Share for static artefacts\n- Thread Sharing between Codex and Claude sessions\n- Moltbook drafts, reply notifications, and approval flow\n\n### What Still Feels Experimental\n\nThese are good places to expect iteration:\n\n- provider-specific UX differences between Codex and Claude\n- the exact shape of cross-session Thread Sharing semantics\n- A2A execution policies and how different agent runtimes plug in\n- higher-level automation patterns around Moltbook and external agent workflows\n\nIf you are building on `viveworker`, the safest bet is to target the core control-loop idea:\nyour tool keeps running where it already runs, and `viveworker` provides the mobile decision surface around it.\n\n### Works With viveworker\n\nAs a practical rule of thumb, a tool fits `viveworker` well if it can do at least one of these:\n\n- emit an approval or yes/no gate before doing something consequential\n- ask a structured question or plan check that can be answered on mobile\n- produce a completion or \"done, here is what happened\" summary\n- hand back a static artefact that is better delivered as a private link than a chat blob\n- receive or send a task through A2A\n- accept a thread handoff, review request, or note from another session\n\nIf your tool can already express work in those terms, it is usually a good candidate for `viveworker` integration.\n\n### Current Working Model\n\nThis is the current mental model for integrations. It is intentionally lightweight and should be read as a working surface, not a frozen public spec.\n\n- **approval**: a user decision is required before the tool continues\n- **choice / plan check**: the tool needs a structured answer, not free-form chat\n- **completion**: the tool finished a unit of work and should surface a summary\n- **code / file change**: the tool changed files and the user may want to review them from the phone\n- **thread share / handoff**: context should move from one session to another with approval in the loop\n- **file share**: a report, prototype, image, or CSV should be delivered as a private URL\n- **a2a task**: an external agent wants work done and the request should land in the same approval flow\n\nIn other words, the stable idea is not \"one provider's internal protocol.\" It is a common mobile control loop for these kinds of events.\n\n### Best Integration Paths Right Now\n\nIf you are deciding where to plug in, the shortest paths today are:\n\n- **Codex / desktop-integrated tools**: route decisions and thread handoffs into the local bridge\n- **Claude Desktop / Claude Code**: use hooks to surface approvals, questions, completions, and file changes\n- **external agents**: use A2A for task exchange\n- **static outputs**: use File Share for reports, prototypes, screenshots, and CSVs\n- **social / outbound agent activity**: use the same approval loop that Moltbook already uses\n\nIf you can map your tool onto one of those paths, you probably do not need a brand-new mobile UX.\n\n## Security Model\n\n- pair devices only on a trusted LAN\n- do not expose the bridge directly to the Internet\n- Remote connection uses a relay only for rendezvous/transport; paired-device traffic is end-to-end encrypted to your bridge\n- relay tokens can be rotated manually and are refreshed automatically during LAN enrollment after the rotation window\n- remote connection activity is recorded locally in `~/.viveworker/remote-pairing-audit.jsonl`\n- public relay analytics expose only coarse, delayed adoption counters; detailed relay health and abuse counters require an operator admin token\n- relay analytics never store prompts, replies, file contents, file paths, command text, relay tokens, public keys, or IP addresses\n- if you lose a paired device, revoke it from `Settings \u003e Devices`\n- use `pair` only when you want to add another trusted device\n- A2A relay authentication: external agents must provide a valid API key (`X-A2A-Key` header), and registration requires GitHub OAuth\n\n## Optional `ntfy`\n\n`ntfy` is optional.\n\nStart with `viveworker` and Web Push first.\nIf you later want a second wake-up notification path, you can add `ntfy` alongside it.\n\n## Troubleshooting\n\n- If the `.local` URL does not open, use the printed IP-based URL\n- If Remote connection does not work off-LAN, open `Settings \u003e Remote connection` once on the same Wi-Fi as the Mac and confirm the device is registered\n- If pairing has expired, run `npx viveworker pair`\n- If notifications do not appear, make sure you opened the Home Screen app, not just a browser tab\n- If Web Push is enabled, make sure you are opening the HTTPS URL\n- On some devices, local CA trust must be enabled manually before HTTPS works\n- Web Push depends on the browser/platform push service — make sure you are using the Home Screen app, not a regular browser tab\n- If you are stuck, run:\n\n```bash\nnpx viveworker status\nnpx viveworker doctor\nnpx viveworker doctor --fix\n```\n\n## Roadmap\n\nPlanned next steps include:\n\n- Windows support\n- ✅ ~~image attachment support from mobile~~ (Mar 26, 2026)\n- ✅ ~~Android support~~ (Apr 1, 2026)\n- ✅ ~~Moltbook integration~~ (Apr 10, 2026)\n- ✅ ~~A2A protocol support~~ (Apr 12, 2026)\n- ✅ ~~File Share~~ (Apr 18, 2026)\n- ✅ ~~Auto Pilot~~ (Apr 21, 2026)\n- ✅ ~~x402 / pay-per-unlock flow (testnet)~~ (Apr 25, 2026)\n- ✅ ~~Remote connection~~ (Apr 28, 2026)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviveworker-dev%2Fviveworker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviveworker-dev%2Fviveworker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviveworker-dev%2Fviveworker/lists"}