elvarone-bridge 0.1.0__tar.gz

elvarone_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: elvarone-bridge
+Version: 0.1.0
+Summary: ElvarOne compute bridge — an MCP server that lets the phone agent run code, take screenshots and leave reports on your computer, and lets your desktop coding agent (Claude Code, Codex) answer them.
+Author: ElvarOne
+License: Apache-2.0
+Project-URL: Homepage, https://agoradigest.com/dm
+Project-URL: Source, https://github.com/shichuanqiong/ElvarAgent
+Keywords: mcp,elvarone,agent,bridge,claude-code,codex,screenshot
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: No Input/Output (Daemon)
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.10
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: httpx>=0.27
+Provides-Extra: agoradm
+Requires-Dist: agoradm>=0.13.0; extra == "agoradm"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# elvarone-bridge
+
+The ElvarOne phone agent's compute bridge: a small MCP server on your
+computer that lets the agent run Python and shell commands, take
+screenshots it can actually look at, publish files, and leave written
+reports that the coding agent on your computer (Claude Code or Codex)
+answers automatically.
+
+```
+pip install elvarone-bridge
+elvarone-bridge init
+```
+
+`init` mints a token, writes `~/ElvarBridge/config.env`, installs a
+background service (launchd on macOS, a systemd user unit on Linux, a
+Task Scheduler command on Windows) and prints the URL + token to enter
+on the phone: **Settings → AI Brain → MCP Servers → Add**.
+
+## Let your desktop AI set it up
+
+Paste this to Claude Code, Codex, Cursor or any coding agent on the
+computer you want to connect:
+
+> Install the ElvarOne compute bridge on this computer: `pip install elvarone-bridge` (use a venv or pipx if you prefer), then run `elvarone-bridge init --agent claude --project <the project you want me to answer questions about>`. Show me the "Phone settings" block it prints (URL and token) so I can enter them in the ElvarOne app. Then run `elvarone-bridge doctor` and fix anything it flags. Add this line to your project instructions (CLAUDE.md or AGENTS.md): "At the start of each session, list ~/ElvarBridge/reports/*.md and answer any file with status: unread; write replies as <stamp>-reply-<slug>.md in the same folder and set the report's status to read."
+
+Replace `--agent claude` with `--agent codex` for Codex, or `--agent none`
+to keep reports for a human session only.
+
+## What the phone agent gets
+
+| tool | what it does |
+|---|---|
+| `run_shell`, `run_python`, `read_file` | compute and files inside `~/ElvarBridge` (the shell is human-approved on the phone for every call) |
+| `screenshot(app, max_width, delay_s)` | capture the screen, downscale, return a **signed, expiring URL** the phone's `view_image` reads — no token in the link |
+| `publish_file(path)` | same signed link for any file in the workdir |
+| `report_to_desktop_agent(title, body, kind, from_agent)` | file a bug / request / finding / question in `~/ElvarBridge/reports/` |
+| `list_reports(status)`, `mark_report(name, status)` | see replies, close them |
+| `/browser/mcp` | Playwright MCP on this computer behind the same token |
+
+## Auto-replies
+
+When `BRIDGE_DESKTOP_AGENT` is `claude` or `codex` (auto-detected), every
+report starts a **read-only** run of that agent in `BRIDGE_AGENT_CWD`
+(`claude -p … --allowedTools Read,Grep,Glob,LS --max-turns 8` or
+`codex exec --sandbox read-only …`). The answer lands as
+`reports/<stamp>-reply-<slug>.md`, the report becomes `status: answered`,
+and a desktop notification fires. The worker never edits files; when a
+change is needed it says "needs a human coding session", and your next
+session picks the report up from the mailbox.
+
+The desktop agent must be logged in for the user running the bridge:
+run `claude` (then `/login`) or `codex login` once in a terminal.
+`elvarone-bridge doctor` checks this.
+
+### Telling the phone
+
+Set `AGORADM_TOKEN` (an AgoraDM bot token for this computer — pair one at
+agoradigest.com/bring-agent) and `BRIDGE_NOTIFY_BOT` (the phone agent's
+bot id) and install the extra: `pip install 'elvarone-bridge[agoradm]'`.
+The bridge then DMs the phone agent when a reply is ready; the DM wakes
+ElvarOne, so the phone reads the answer without polling.
+
+## Security
+
+- The token is required on every request. `init` mints a 32-byte random one.
+- Binds `0.0.0.0` (LAN + Tailscale). **Never port-forward it to the internet.**
+  Install Tailscale on both devices to use the bridge away from home.
+- Every remote call is approved on the phone. Pre-approve only read-only
+  tools (`screenshot`, `list_reports`, `read_file`, `report_to_desktop_agent`).
+- Commands that would stop the bridge's own services are refused.
+- Published files are signed links valid `BRIDGE_FILE_URL_TTL_S` (2 h) for one file.
+
+## Configuration
+
+`~/ElvarBridge/config.env` (mode 600), or the same keys in the environment:
+
+```
+BRIDGE_TOKEN=…             required
+BRIDGE_PORT=8787
+BRIDGE_BIND=0.0.0.0
+BRIDGE_PUBLIC_URL=         override the URL handed to the phone
+BRIDGE_FILE_URL_TTL_S=7200
+BRIDGE_DESKTOP_AGENT=      claude | codex | none (auto)
+BRIDGE_AGENT_CWD=          project the desktop agent reads (default ~/ElvarBridge)
+BRIDGE_AGENT_MAX_TURNS=8
+BRIDGE_AGENT_TIMEOUT_S=600
+BRIDGE_CLAUDE_ARGS=        extra flags for claude -p (e.g. --max-budget-usd 0.50)
+BRIDGE_NOTIFY_DESKTOP=1
+AGORADM_TOKEN=             optional, see "Telling the phone"
+BRIDGE_NOTIFY_BOT=
+```
+
+Upgrading from the original `mac_bridge.py` launchd setup: `pip install -e .`
+in the same venv keeps the old plist working; `elvarone-bridge init` migrates
+to the packaged service.

elvarone_bridge-0.1.0/README.md

@@ -0,0 +1,95 @@
+# elvarone-bridge
+
+The ElvarOne phone agent's compute bridge: a small MCP server on your
+computer that lets the agent run Python and shell commands, take
+screenshots it can actually look at, publish files, and leave written
+reports that the coding agent on your computer (Claude Code or Codex)
+answers automatically.
+
+```
+pip install elvarone-bridge
+elvarone-bridge init
+```
+
+`init` mints a token, writes `~/ElvarBridge/config.env`, installs a
+background service (launchd on macOS, a systemd user unit on Linux, a
+Task Scheduler command on Windows) and prints the URL + token to enter
+on the phone: **Settings → AI Brain → MCP Servers → Add**.
+
+## Let your desktop AI set it up
+
+Paste this to Claude Code, Codex, Cursor or any coding agent on the
+computer you want to connect:
+
+> Install the ElvarOne compute bridge on this computer: `pip install elvarone-bridge` (use a venv or pipx if you prefer), then run `elvarone-bridge init --agent claude --project <the project you want me to answer questions about>`. Show me the "Phone settings" block it prints (URL and token) so I can enter them in the ElvarOne app. Then run `elvarone-bridge doctor` and fix anything it flags. Add this line to your project instructions (CLAUDE.md or AGENTS.md): "At the start of each session, list ~/ElvarBridge/reports/*.md and answer any file with status: unread; write replies as <stamp>-reply-<slug>.md in the same folder and set the report's status to read."
+
+Replace `--agent claude` with `--agent codex` for Codex, or `--agent none`
+to keep reports for a human session only.
+
+## What the phone agent gets
+
+| tool | what it does |
+|---|---|
+| `run_shell`, `run_python`, `read_file` | compute and files inside `~/ElvarBridge` (the shell is human-approved on the phone for every call) |
+| `screenshot(app, max_width, delay_s)` | capture the screen, downscale, return a **signed, expiring URL** the phone's `view_image` reads — no token in the link |
+| `publish_file(path)` | same signed link for any file in the workdir |
+| `report_to_desktop_agent(title, body, kind, from_agent)` | file a bug / request / finding / question in `~/ElvarBridge/reports/` |
+| `list_reports(status)`, `mark_report(name, status)` | see replies, close them |
+| `/browser/mcp` | Playwright MCP on this computer behind the same token |
+
+## Auto-replies
+
+When `BRIDGE_DESKTOP_AGENT` is `claude` or `codex` (auto-detected), every
+report starts a **read-only** run of that agent in `BRIDGE_AGENT_CWD`
+(`claude -p … --allowedTools Read,Grep,Glob,LS --max-turns 8` or
+`codex exec --sandbox read-only …`). The answer lands as
+`reports/<stamp>-reply-<slug>.md`, the report becomes `status: answered`,
+and a desktop notification fires. The worker never edits files; when a
+change is needed it says "needs a human coding session", and your next
+session picks the report up from the mailbox.
+
+The desktop agent must be logged in for the user running the bridge:
+run `claude` (then `/login`) or `codex login` once in a terminal.
+`elvarone-bridge doctor` checks this.
+
+### Telling the phone
+
+Set `AGORADM_TOKEN` (an AgoraDM bot token for this computer — pair one at
+agoradigest.com/bring-agent) and `BRIDGE_NOTIFY_BOT` (the phone agent's
+bot id) and install the extra: `pip install 'elvarone-bridge[agoradm]'`.
+The bridge then DMs the phone agent when a reply is ready; the DM wakes
+ElvarOne, so the phone reads the answer without polling.
+
+## Security
+
+- The token is required on every request. `init` mints a 32-byte random one.
+- Binds `0.0.0.0` (LAN + Tailscale). **Never port-forward it to the internet.**
+  Install Tailscale on both devices to use the bridge away from home.
+- Every remote call is approved on the phone. Pre-approve only read-only
+  tools (`screenshot`, `list_reports`, `read_file`, `report_to_desktop_agent`).
+- Commands that would stop the bridge's own services are refused.
+- Published files are signed links valid `BRIDGE_FILE_URL_TTL_S` (2 h) for one file.
+
+## Configuration
+
+`~/ElvarBridge/config.env` (mode 600), or the same keys in the environment:
+
+```
+BRIDGE_TOKEN=…             required
+BRIDGE_PORT=8787
+BRIDGE_BIND=0.0.0.0
+BRIDGE_PUBLIC_URL=         override the URL handed to the phone
+BRIDGE_FILE_URL_TTL_S=7200
+BRIDGE_DESKTOP_AGENT=      claude | codex | none (auto)
+BRIDGE_AGENT_CWD=          project the desktop agent reads (default ~/ElvarBridge)
+BRIDGE_AGENT_MAX_TURNS=8
+BRIDGE_AGENT_TIMEOUT_S=600
+BRIDGE_CLAUDE_ARGS=        extra flags for claude -p (e.g. --max-budget-usd 0.50)
+BRIDGE_NOTIFY_DESKTOP=1
+AGORADM_TOKEN=             optional, see "Telling the phone"
+BRIDGE_NOTIFY_BOT=
+```
+
+Upgrading from the original `mac_bridge.py` launchd setup: `pip install -e .`
+in the same venv keeps the old plist working; `elvarone-bridge init` migrates
+to the packaged service.

elvarone_bridge-0.1.0/elvarone_bridge/__init__.py

@@ -0,0 +1,12 @@
+"""elvarone-bridge — the phone agent's compute bridge on your computer.
+
+    elvarone-bridge init      # mint a token, install the service, print phone settings
+    elvarone-bridge run       # run in the foreground
+    elvarone-bridge doctor    # check token, reachability, desktop agent login
+
+See README.md for the paste-to-your-desktop-AI setup prompt.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

elvarone_bridge-0.1.0/elvarone_bridge/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

elvarone_bridge-0.1.0/elvarone_bridge/autoreply.py

@@ -0,0 +1,135 @@
+"""Auto-reply: when the phone agent files a report, ask the desktop coding
+agent on this computer to read it and answer — then tell everyone.
+
+    report written → worker thread → `claude -p` (or `codex exec`), READ-ONLY
+                  → reply file in ~/ElvarBridge/reports/
+                  → report status: answered
+                  → OS notification + (optional) AgoraDM DM to the phone agent
+
+The worker never edits files: it runs with read-only tools and a turn
+cap, so a bad report cannot turn into a bad commit. Anything that needs
+code changes ends with "needs a human coding session", and the human's
+session picks the report up from the mailbox as before.
+
+The phone agent is told "your reply is ready" over AgoraDM when
+AGORADM_TOKEN and BRIDGE_NOTIFY_BOT are configured — that push wakes
+ElvarOne, so the phone reads the answer without polling.
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import subprocess
+import threading
+from typing import Optional
+
+from . import config
+from .mailbox import Report, set_status, write_reply
+
+_LOG = logging.getLogger("elvarone-bridge.autoreply")
+
+PROMPT = """You are the desktop coding agent on this computer. A phone agent (ElvarOne) filed the report below in ~/ElvarBridge/reports/{name}.
+
+Read it, verify what you can in the project at {cwd} (read-only: look at code and logs, run nothing that changes anything), and write a concise reply:
+1. what in the report is confirmed, what is not (with file/line pointers when you looked);
+2. the likely cause;
+3. what to do next — and say plainly "needs a human coding session" when a change is required;
+4. anything the phone agent should do differently.
+
+Reply in the language the report is written in. Markdown, under 400 words. Do not modify files.
+
+--- REPORT ({kind}, from {sender}) ---
+{body}
+--- END ---"""
+
+
+def _claude_cmd(prompt: str) -> list[str]:
+    turns = str(config.env_int("BRIDGE_AGENT_MAX_TURNS", 8))
+    extra = shlex.split(config.env("BRIDGE_CLAUDE_ARGS"))
+    return ["claude", "-p", prompt, "--output-format", "text", "--max-turns", turns,
+            "--allowedTools", "Read,Grep,Glob,LS", *extra]
+
+
+def _codex_cmd(prompt: str) -> list[str]:
+    extra = shlex.split(config.env("BRIDGE_CODEX_ARGS"))
+    return ["codex", "exec", "--sandbox", "read-only", *extra, prompt]
+
+
+def run_agent(report: Report) -> tuple[str, str]:
+    """Returns (agent_name, reply_text). Raises on failure."""
+    agent = config.desktop_agent()
+    if agent == "none":
+        raise RuntimeError("no desktop agent configured (BRIDGE_DESKTOP_AGENT=claude|codex)")
+    prompt = PROMPT.format(name=report.name, cwd=config.agent_cwd(), kind=report.kind,
+                           sender=report.sender or "phone agent", body=report.body[:12000])
+    cmd = _claude_cmd(prompt) if agent == "claude" else _codex_cmd(prompt)
+    timeout = config.env_int("BRIDGE_AGENT_TIMEOUT_S", 600)
+    config.agent_cwd().mkdir(parents=True, exist_ok=True)
+    proc = subprocess.run(cmd, cwd=str(config.agent_cwd()), capture_output=True, text=True, timeout=timeout,
+                          stdin=subprocess.DEVNULL)
+    out = (proc.stdout or "").strip()
+    err = (proc.stderr or "").strip()
+    if proc.returncode != 0 or not out:
+        raise RuntimeError(f"{agent} exited {proc.returncode}: {(err or out)[:600]}")
+    return agent, out
+
+
+def notify_desktop(title: str, text: str) -> None:
+    if config.env("BRIDGE_NOTIFY_DESKTOP", "1") != "1":
+        return
+    try:
+        if config.is_macos():
+            safe_t = title.replace('"', "'")[:80]
+            safe_x = text.replace('"', "'")[:200]
+            subprocess.run(["osascript", "-e", f'display notification "{safe_x}" with title "{safe_t}"'],
+                           capture_output=True, timeout=10)
+        elif not config.is_windows():
+            subprocess.run(["notify-send", title[:80], text[:200]], capture_output=True, timeout=10)
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+
+def notify_phone(report: Report, reply: Report) -> Optional[str]:
+    """DM the phone agent over AgoraDM that its report has an answer.
+    Returns a short status string for logs, or None when not configured."""
+    tok = config.env("AGORADM_TOKEN")
+    bot = config.env("BRIDGE_NOTIFY_BOT")
+    if not tok or not bot:
+        return None
+    try:
+        from agoradm import AgentClient  # optional dependency
+    except ImportError:
+        return "agoradm not installed (pip install 'elvarone-bridge[agoradm]')"
+    excerpt = reply.body.strip()
+    if len(excerpt) > 1500:
+        excerpt = excerpt[:1500].rstrip() + " …"
+    text = (
+        f"Your report “{report.title}” has a reply from the desktop agent on this computer.\n"
+        f"Read the full file with read_file path=reports/{reply.name} on the bridge.\n\n{excerpt}"
+    )
+    try:
+        client = AgentClient(token=tok)
+        r = client.dm.send(bot, text)
+        return f"DM sent to {bot}: {getattr(r, 'task_id', r) if r is not None else 'ok'}"
+    except Exception as e:  # noqa: BLE001
+        return f"DM failed: {e}"
+
+
+def answer_in_background(report: Report) -> None:
+    def _work() -> None:
+        try:
+            agent, text = run_agent(report)
+        except Exception as e:  # noqa: BLE001
+            _LOG.warning("auto-reply for %s failed: %s", report.name, e)
+            notify_desktop("ElvarOne report waiting", f"{report.title} — no auto-reply ({e})"[:200])
+            return
+        reply = write_reply(report, text, sender=f"{agent} (auto-reply)")
+        set_status(report, "answered")
+        _LOG.info("auto-replied to %s with %s", report.name, reply.name)
+        notify_desktop("ElvarOne report answered", report.title)
+        status = notify_phone(report, reply)
+        if status:
+            _LOG.info("phone notify: %s", status)
+
+    threading.Thread(target=_work, name=f"autoreply:{report.name}", daemon=True).start()

elvarone_bridge-0.1.0/elvarone_bridge/cli.py

@@ -0,0 +1,231 @@
+"""elvarone-bridge command line.
+
+    elvarone-bridge init [--token T] [--port N] [--agent claude|codex|none] [--project DIR]
+        Mint a token (or take yours), write ~/ElvarBridge/config.env, install
+        a background service (macOS launchd / Linux systemd user unit; prints a
+        Task Scheduler command on Windows) and print the settings for the phone.
+    elvarone-bridge run       Run in the foreground (what the service runs).
+    elvarone-bridge doctor    Check config, port, reachability, desktop agent login.
+    elvarone-bridge settings  Print the phone-side settings block again.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import secrets
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__, config
+
+SERVICE_MAC = "com.elvarone.bridge"
+SERVICE_LINUX = "elvarone-bridge"
+
+
+def _write_config(values: dict[str, str]) -> None:
+    config.ensure_dirs()
+    existing = config.load_config_file()
+    existing.update({k: v for k, v in values.items() if v})
+    lines = ["# elvarone-bridge configuration (mode 600). Edit and restart the service."]
+    for k, v in existing.items():
+        lines.append(f"{k}={v}")
+    config.CONFIG_FILE.write_text("\n".join(lines) + "\n")
+    try:
+        os.chmod(config.CONFIG_FILE, 0o600)
+    except OSError:
+        pass
+
+
+def _python() -> str:
+    return sys.executable
+
+
+def _install_service() -> str:
+    """Install/refresh the background service. Returns the restart command."""
+    if config.is_macos():
+        plist = Path.home() / "Library" / "LaunchAgents" / f"{SERVICE_MAC}.plist"
+        plist.parent.mkdir(parents=True, exist_ok=True)
+        log = config.LOGDIR / "bridge.log"
+        path_env = "/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+        plist.write_text(f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key><string>{SERVICE_MAC}</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>{_python()}</string>
+        <string>-m</string>
+        <string>elvarone_bridge</string>
+        <string>run</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key><string>{path_env}</string>
+        <key>HOME</key><string>{Path.home()}</string>
+    </dict>
+    <key>WorkingDirectory</key><string>{config.WORKDIR}</string>
+    <key>RunAtLoad</key><true/>
+    <key>KeepAlive</key><true/>
+    <key>StandardOutPath</key><string>{log}</string>
+    <key>StandardErrorPath</key><string>{log}</string>
+</dict>
+</plist>
+""")
+        uid = os.getuid()
+        subprocess.run(["launchctl", "bootout", f"gui/{uid}", str(plist)], capture_output=True)
+        subprocess.run(["launchctl", "bootstrap", f"gui/{uid}", str(plist)], capture_output=True)
+        return f"launchctl kickstart -k gui/{uid}/{SERVICE_MAC}"
+    if config.is_windows():
+        cmd = f'schtasks /Create /F /SC ONLOGON /TN ElvarOneBridge /TR "\\"{_python()}\\" -m elvarone_bridge run"'
+        return f"(install once) {cmd}\n(restart) schtasks /End /TN ElvarOneBridge & schtasks /Run /TN ElvarOneBridge"
+    unit = Path.home() / ".config" / "systemd" / "user" / f"{SERVICE_LINUX}.service"
+    unit.parent.mkdir(parents=True, exist_ok=True)
+    unit.write_text(f"""[Unit]
+Description=ElvarOne compute bridge
+After=network.target
+
+[Service]
+ExecStart={_python()} -m elvarone_bridge run
+WorkingDirectory={config.WORKDIR}
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target
+""")
+    subprocess.run(["systemctl", "--user", "daemon-reload"], capture_output=True)
+    subprocess.run(["systemctl", "--user", "enable", "--now", SERVICE_LINUX], capture_output=True)
+    return f"systemctl --user restart {SERVICE_LINUX}"
+
+
+def _addresses() -> tuple[str, str]:
+    from .server_addr import lan_ip, tailscale_ip  # light helpers, no server import
+
+    return tailscale_ip(), lan_ip()
+
+
+def settings_block() -> str:
+    config.load_config_file()
+    ts, lan = _addresses()
+    port = config.port()
+    tok = config.token()
+    lines = [
+        "── Phone settings (ElvarOne → Settings → AI Brain → MCP Servers → Add) ──",
+        "  name:  mac   (or pc / laptop — whatever you call this computer)",
+    ]
+    if ts:
+        lines.append(f"  URL:   http://{ts}:{port}/mcp     (Tailscale — works away from home)")
+        lines.append(f"         http://{lan}:{port}/mcp     (LAN only)")
+    else:
+        lines.append(f"  URL:   http://{lan}:{port}/mcp     (LAN; install Tailscale on both devices to use it away from home)")
+    lines.append(f"  token: {tok}")
+    lines.append("  Pre-approve (optional, read-only): screenshot, list_reports, read_file, report_to_desktop_agent")
+    lines.append(f"  Desktop agent for auto-replies: {config.desktop_agent()}")
+    return "\n".join(lines)
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    tok = args.token or config.env("BRIDGE_TOKEN") or secrets.token_urlsafe(32)
+    values = {"BRIDGE_TOKEN": tok, "BRIDGE_PORT": str(args.port or config.port())}
+    if args.agent:
+        values["BRIDGE_DESKTOP_AGENT"] = args.agent
+    if args.project:
+        values["BRIDGE_AGENT_CWD"] = str(Path(args.project).expanduser().resolve())
+    if args.agoradm_token:
+        values["AGORADM_TOKEN"] = args.agoradm_token
+    if args.notify_bot:
+        values["BRIDGE_NOTIFY_BOT"] = args.notify_bot
+    _write_config(values)
+    os.environ["BRIDGE_TOKEN"] = tok
+    restart = _install_service() if not args.no_service else "(service not installed; run `elvarone-bridge run`)"
+    print(f"elvarone-bridge {__version__} configured at {config.CONFIG_FILE}")
+    print(f"restart command: {restart}")
+    print()
+    print(settings_block())
+    print()
+    print("Next: on the phone add the server with the URL + token above, then ask the phone agent to run `screenshot`.")
+    return 0
+
+
+def cmd_run(_args: argparse.Namespace) -> int:
+    from .server import main
+
+    main()
+    return 0
+
+
+def cmd_doctor(_args: argparse.Namespace) -> int:
+    config.load_config_file()
+    config.ensure_dirs()
+    ok = True
+
+    def line(good: bool, text: str) -> None:
+        nonlocal ok
+        ok = ok and good
+        print(("  ✓ " if good else "  ✗ ") + text)
+
+    print(f"elvarone-bridge {__version__} · python {sys.version.split()[0]} · {sys.platform}")
+    line(bool(config.token()), f"token configured ({config.CONFIG_FILE})" if config.token() else "no BRIDGE_TOKEN — run `elvarone-bridge init`")
+    ts, lan = _addresses()
+    line(True, f"addresses: tailscale={ts or 'none'} lan={lan} port={config.port()}")
+    try:
+        import httpx
+
+        r = httpx.get(f"http://127.0.0.1:{config.port()}/healthz", timeout=3)
+        line(r.status_code == 200, f"service answering on port {config.port()}: {r.text[:120]}")
+    except Exception as e:  # noqa: BLE001
+        line(False, f"service not answering on port {config.port()} ({e.__class__.__name__}); start it with `elvarone-bridge run` or the service")
+    agent = config.desktop_agent()
+    if agent == "none":
+        line(True, "desktop agent: none (reports wait for a human session)")
+    else:
+        exe = shutil.which(agent)
+        line(bool(exe), f"desktop agent: {agent} at {exe or 'not on PATH'}")
+        if exe:
+            try:
+                cmd = [agent, "-p", "Reply with exactly: BRIDGE_OK", "--max-turns", "1"] if agent == "claude" else [agent, "exec", "--sandbox", "read-only", "Reply with exactly: BRIDGE_OK"]
+                proc = subprocess.run(cmd, capture_output=True, text=True, timeout=90, cwd=str(config.agent_cwd()), stdin=subprocess.DEVNULL)
+                out = (proc.stdout + proc.stderr).strip()
+                line("BRIDGE_OK" in out, f"{agent} answers non-interactively" if "BRIDGE_OK" in out else f"{agent} could not answer: {out[:160]} — log in once (`{agent}` then /login) in a terminal as this user")
+            except Exception as e:  # noqa: BLE001
+                line(False, f"{agent} check failed: {e}")
+    if config.env("AGORADM_TOKEN") and config.env("BRIDGE_NOTIFY_BOT"):
+        line(True, f"phone notifications over AgoraDM → {config.env('BRIDGE_NOTIFY_BOT')}")
+    else:
+        line(True, "phone notifications: off (set AGORADM_TOKEN + BRIDGE_NOTIFY_BOT to DM the phone agent when a reply is ready)")
+    if config.is_macos():
+        print("  · Screen Recording: if `screenshot` returns only wallpaper, enable it for the app that launches the bridge in System Settings → Privacy & Security.")
+    return 0 if ok else 1
+
+
+def cmd_settings(_args: argparse.Namespace) -> int:
+    print(settings_block())
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="elvarone-bridge", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"elvarone-bridge {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    i = sub.add_parser("init", help="configure, install the service, print phone settings")
+    i.add_argument("--token", help="use this bearer token instead of minting one")
+    i.add_argument("--port", type=int)
+    i.add_argument("--agent", choices=["claude", "codex", "none"], help="desktop agent for auto-replies")
+    i.add_argument("--project", help="project directory the desktop agent reads when answering reports")
+    i.add_argument("--agoradm-token", help="AgoraDM bot token so replies are pushed to the phone agent")
+    i.add_argument("--notify-bot", help="the phone agent's bot id to DM when a reply is ready")
+    i.add_argument("--no-service", action="store_true", help="only write config; do not install a background service")
+    i.set_defaults(fn=cmd_init)
+    sub.add_parser("run", help="run in the foreground").set_defaults(fn=cmd_run)
+    sub.add_parser("doctor", help="check the installation").set_defaults(fn=cmd_doctor)
+    sub.add_parser("settings", help="print the phone-side settings").set_defaults(fn=cmd_settings)
+    args = p.parse_args(argv)
+    return int(args.fn(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())