Metadata-Version: 2.4
Name: relayai-local-bridge
Version: 0.1.2
Summary: Local Claude Code and Codex bridge for RelayAI sessions
Author: Alex Nuccio
Project-URL: Homepage, https://relayai.nrsoftware.ai/onboarding
Project-URL: Documentation, https://relayai.nrsoftware.ai/onboarding
Project-URL: Repository, https://github.com/anuccio15/relay-ai
Project-URL: Issues, https://github.com/anuccio15/relay-ai/issues
Keywords: relayai,bridge,claude-code,codex,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: claude-agent-sdk==0.1.49
Requires-Dist: httpx<0.29,>=0.27
Requires-Dist: websockets<16,>=15

# RelayAI Local Bridge

This package lets a local machine claim a RelayAI bridge session and process incoming app messages using a local Claude or Codex runtime.

## Prerequisites

Before starting the RelayAI bridge on a machine, install and authenticate any local runtimes you want that bridge to support.

### Claude Code

RelayAI does not install Claude Code for you. Install Claude Code locally first, then make sure it can start successfully from your terminal.

Official setup docs:

- [Anthropic Claude Code setup](https://docs.anthropic.com/en/docs/claude-code/setup)

Typical install:

```bash
npm install -g @anthropic-ai/claude-code
claude
```

Notes:

- Anthropic's current docs list Node.js 18+ as a prerequisite.
- Run `claude` once and complete authentication before using Claude-backed bridge sessions.

### Codex CLI

RelayAI does not install Codex for you. Install the Codex CLI locally first, then make sure it is authenticated and runnable from your terminal.

Official sources:

- [OpenAI Codex GitHub repository](https://github.com/openai/codex)
- [Codex install docs in the repository](https://github.com/openai/codex/blob/main/docs/install.md)

Typical install:

```bash
# npm
npm install -g @openai/codex

# or Homebrew on macOS
brew install --cask codex

# then start Codex and complete sign-in
codex
```

Notes:

- The current Codex README documents `npm install -g @openai/codex` and `brew install --cask codex`.
- Run `codex` once and complete either ChatGPT sign-in or API-key setup before using Codex-backed bridge sessions.
- RelayAI uses the local `codex` CLI and `codex app-server`; the bridge will report Codex as unavailable until the CLI is installed and authenticated.

## What it does

1. Authenticates as a paired bridge device
2. Waits for a RelayAI bridge-session announcement from the app
3. Subscribes to `/api/sessions/{id}/events/stream`
4. Watches for new `user` messages
5. Runs Claude or Codex locally on your machine
6. Streams assistant deltas back to RelayAI
7. Returns to idle when a session is stopped in the app

## Install

Recommended install for users:

```bash
python3 -m pip install --upgrade relayai-local-bridge
```

That installs the published RelayAI bridge package from PyPI. It does **not** install Claude Code or Codex CLI for you.

If you are working from a local RelayAI checkout and want the unreleased repo version instead:

```bash
cd local-bridge
python3 -m pip install .
```

## Update an existing bridge

For most users:

```bash
python3 -m pip install --upgrade relayai-local-bridge
```

If you are updating from a local RelayAI checkout after pulling new repo changes:

```bash
cd /Users/alexnuccio/Documents/projects/RelayAI/local-bridge
python3 -m pip install --upgrade .
```

You do not need to pair again after a normal bridge update. Re-pair only if you intentionally switch to a different RelayAI account or want to clear the saved bridge credentials.

## First run

Preferred launch command:

```bash
relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo \
  --claude-cli-path "$(command -v claude)" \
  --codex-cli-path "$(command -v codex)"
```

Those CLI-path flags are optional. The bridge can still run without them, but passing the explicit local executable paths is the preferred setup because it makes the runtime choice unambiguous and avoids depending on whatever binary the SDK or shell happens to resolve by default.

Minimal launch command:

```bash
relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo
```

If the bridge is not paired yet, it prints a one-time pairing code. Approve that code in the app under `Settings -> Bridge Pairing`.

After approval, the bridge stores its own credentials locally and reuses them automatically.

## Re-pair to a new account or phone

If you sign into RelayAI with a different account, or you want this machine to pair again from scratch, clear the stored bridge credentials and rerun the bridge:

```bash
relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo \
  --reset-auth
```

That removes the saved bridge authentication for this machine and starts a fresh pairing flow. Approve the new one-time pairing code in the app under `Settings -> Bridge Pairing`.

If an older installed bridge exits with `Invalid refresh token.`, run the same command with `--reset-auth` once. Newer bridge versions clear expired bridge credentials automatically and start pairing again.

## Optional flags

- `--session-id` to attach to an existing RelayAI session
- `--ca-bundle` to point Python at a specific trusted CA bundle if your local OpenSSL trust store cannot validate the RelayAI certificate chain
- `--reset-auth` to clear stored bridge credentials and force a new pairing flow
- `--credentials-file` to override the default credential storage location
- `--claude-cli-path` to override the Claude CLI path for bridge-backed Claude sessions
- `--codex-cli-path` to override the Codex CLI path for bridge-backed Codex sessions
- `--verbose` to enable debug-level bridge, Claude, and Codex runtime logs
- `--log-level DEBUG|INFO|WARNING|ERROR` to set the bridge log level explicitly

## Debugging

For verbose bridge logs while debugging a stuck session:

```bash
relayai-local-bridge \
  --base-url https://relay.nrsoftware.ai \
  --cwd /path/to/local/repo \
  --verbose
```

You can also set `RELAYAI_VERBOSE=1` or `RELAYAI_LOG_LEVEL=DEBUG`.

Verbose logs include:

- RelayAI event receipt for each bridge session
- Claude and Codex turn start/completion details
- first runtime text delta timing
- approval request and resolution flow
- watchdog checks and recovery reasons
- Codex app-server request/notification and stderr tracing

## Notes

- `--cwd` should point at the local repo you want Claude or Codex to work in.
- The published bridge package version is tracked in [pyproject.toml](/Users/alexnuccio/Documents/projects/RelayAI/local-bridge/pyproject.toml) and [__init__.py](/Users/alexnuccio/Documents/projects/RelayAI/local-bridge/local_bridge/__init__.py).
- Your local Claude CLI/login must already be working on that machine before you start Claude bridge sessions.
- Your local Codex CLI/login must already be working on that machine before you start Codex bridge sessions.
- The bridge updates the session `cwd` so RelayAI reflects the local execution path.
- On startup the bridge reports which integrations are available on the machine so the iPhone app can offer only supported bridge runtimes.
- If you omit `--session-id`, the bridge stays idle until you press `Refresh` on the app home page and the app announces active bridge sessions.
- The bridge logs when it starts, when it claims a session, and when a session is stopped/released.
