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.
