RepoRelay

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/reporelay-logo-dark.png">
    <img src="docs/assets/reporelay-logo.png" width="440" alt="RepoRelay">
  </picture>
</p>

<p align="center"><b>Give AI access to your repository &mdash; not your machine.</b></p>

<p align="center">RepoRelay lets ChatGPT safely inspect one local repository
without giving it control of the rest of your computer.</p>

<p align="center">
  <a href="https://github.com/Lukie-81/RepoRelay/actions/workflows/ci.yml"><img src="https://github.com/Lukie-81/RepoRelay/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
  <a href="#before-you-install"><img src="https://img.shields.io/badge/node-%3E%3D22.19%20%3C27-green.svg" alt="Node.js >=22.19 <27"></a>
  <img src="https://img.shields.io/badge/protocol-MCP-6e5494.svg" alt="Model Context Protocol">
</p>

<p align="center">
  <img src="docs/assets/reporelay-hero.png" width="720" alt="RepoRelay architecture: an authenticated AI reviewer reaches the loopback bridge, which exposes bounded read and search access to one approved repository and fixed handoff writers for a separate implementer.">
</p>

<p align="center"><b>ChatGPT &rarr; Secure MCP Tunnel &rarr; tunnel-client &rarr; RepoRelay &rarr; one approved repository</b></p>

<p align="center"><b>Read safe files &middot; Search code &middot; One approved repository &middot; No shell &middot; No Git &middot; No arbitrary writes</b></p>

<p align="center">
  <a href="https://github.com/Lukie-81/RepoRelay/raw/refs/heads/main/docs/assets/reporelay-demo.mp4">
    <img
      src="docs/assets/reporelay-demo.gif"
      width="760"
      alt="RepoRelay onboarding demo showing installation, one approved repository selection, ChatGPT connection, and adding RepoRelay to ChatGPT"
    >
  </a>
</p>

<p align="center">
  <a href="https://github.com/Lukie-81/RepoRelay/raw/refs/heads/main/docs/assets/reporelay-demo.mp4"><b>Watch the full demo &rarr;</b></a>
</p>

<p align="center">
  <a href="#quick-setup">Quick Setup</a> &middot;
  <a href="#youre-connected--what-now">Use It</a> &middot;
  <a href="#chatgpt--coding-agent-handoff">Handoff</a> &middot;
  <a href="#troubleshooting">Troubleshooting</a> &middot;
  <a href="#security">Security</a>
</p>

## What RepoRelay does

RepoRelay is a local, first-party MCP bridge that gives ChatGPT **bounded
access to exactly one approved repository on your computer** &mdash; nothing more.

ChatGPT reviews your code through RepoRelay, and can leave a structured task
for a separate local coding agent (like Codex or Claude) through fixed handoff
files. RepoRelay is the security boundary between ChatGPT and your machine.

```text
ChatGPT reviews/plans
        ↓
RepoRelay
        ↓
Repository reads/searches
+
fixed .ai-handoff writers
        ↓
Codex / another local coding agent implements
```

## How the safety model works

MCP (Model Context Protocol) is the standard that lets ChatGPT call tools.
ChatGPT is the MCP client. RepoRelay is the local MCP server and security
boundary: it decides what ChatGPT may access and exposes exactly one approved
repository at a time. `tunnel-client` is only the secure networking pipe that
carries ChatGPT traffic to your computer.

| Component | Job |
| --- | --- |
| ChatGPT | MCP client — chooses RepoRelay tools. |
| Secure MCP Tunnel | Carries traffic from ChatGPT to your computer. |
| `tunnel-client` | Local network forwarder; points the tunnel at RepoRelay. |
| RepoRelay | MCP server + security boundary; enforces authentication and allowed access. |
| Repository | The one directory ChatGPT is allowed to inspect. |

**What ChatGPT can do through RepoRelay (the normal 7-tool setup):**

```text
✓ inspect files          open_workspace, list_files, read_file
✓ search the repository  search_files
✓ write to three predetermined handoff targets
                         write_next_task, write_review, update_handoff_state
```

**What ChatGPT cannot do:**

```text
✗ run shell commands
✗ run PowerShell
✗ run Git
✗ launch processes
✗ arbitrarily edit source files
✗ delete files
✗ choose arbitrary write targets
✗ access outside the approved repository
```

This is one of RepoRelay's strongest differentiators: ChatGPT can read and plan
against your code, but it gets **no execution capability** and can only write to
a few fixed handoff files you control.

## Before you install

You need:

- **Node.js** `>=22.19` and `<27` (npm is included). Check with
  `node --version`.
- **An existing local project or repository** you want ChatGPT to review. It
  must be a real folder on your computer &mdash; not a drive root and not your
  whole user folder.
- **OpenAI Secure MCP Tunnel access.** RepoRelay reaches ChatGPT through
  OpenAI's Secure MCP Tunnel. See the current
  [OpenAI Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
  for availability, permissions, and plan details.
- **Permission to create/use a custom MCP app** in the target ChatGPT
  workspace (ChatGPT developer mode).

You do **not** need to download anything else. RepoRelay installs the official
OpenAI `tunnel-client` automatically during `reporelay tunnel setup`.

Do not worry about the handoff protocol yet. The quickstart sets up working
handoff files for you and explains them as you go.

## Quick setup

> **Windows paths.** Always quote the full path and keep the backslashes:
>
> ```powershell
> reporelay quickstart "C:\Users\you\Projects\my-app"
> ```
>
> `C:\Users\you\Projects\my-app` is correct. `C:Users\you\Projects\my-app` is
> not &mdash; the backslashes matter.

### 1. Install RepoRelay

```powershell
npm install -g reporelay-mcp@latest
```

Check the install:

```powershell
reporelay --version
```

If `reporelay` is not recognized, see [Troubleshooting](#troubleshooting).

### 2. Start RepoRelay on one repository

```powershell
reporelay quickstart "C:\Projects\my-app"
```

Replace the path with the repository you want to expose. Keep this PowerShell
window open.

You should see:

```text
Ready.
Local MCP: http://127.0.0.1:7676/mcp
```

The normal quickstart enables the **7-tool handoff surface** (4 inspection
tools + 3 fixed handoff writers). RepoRelay now creates a small `.ai-handoff`
workspace and an `AGENTS.md` note so ChatGPT can leave structured tasks and
reviews for a separate local coding agent:

```text
.ai-handoff/NEXT_TASK.md
.ai-handoff/REVIEW.md
.ai-handoff/RESULT.md
.ai-handoff/STATE.json
AGENTS.md
```

**Why does RepoRelay create these?** ChatGPT still cannot run commands, use
Git, or arbitrarily edit your repository. These files are simply a place where
ChatGPT can leave a task, and a separate local coding agent (running on your
own machine, with your own permission) can leave its result. More below in
[ChatGPT ↔ coding-agent handoff](#chatgpt--coding-agent-handoff).

To stop RepoRelay later, press **Ctrl+C** in this window. There is no
`reporelay quickstart --stop`.

### 3. Audit it

Immediately after quickstart, verify RepoRelay's actual security boundary:

```powershell
reporelay audit "C:\Projects\my-app"
```

You should see:

```text
RESULT: PASS
```

Audit starts its own temporary loopback listener and exercises the real
authenticated MCP surface, containment checks, and handoff restrictions. It
does not modify your repository. This validates RepoRelay *before* ChatGPT is
connected.

### 4. Run RepoRelay tunnel setup

In a **second** PowerShell window, run:

```powershell
reporelay tunnel setup
```

This starts the RepoRelay setup wizard. It does everything for you:

```text
✓ installs a RepoRelay-supported OpenAI tunnel-client
✓ verifies it (pinned version + official SHA-256)
✓ opens OpenAI tunnel setup
✓ asks for your tunnel ID
✓ opens OpenAI runtime-key setup
✓ securely stores the pasted key
✓ creates the tunnel profile
✓ tests the complete connection
```

You provide exactly two things, both in OpenAI Platform:

1. **Your Secure MCP Tunnel ID** — the wizard opens
   <https://platform.openai.com/settings/organization/tunnels> in your
   browser. Create or select a tunnel, associate it with your ChatGPT
   workspace, and paste its `tunnel_id` back in the terminal.
2. **A runtime API key** — the wizard opens
   <https://platform.openai.com/settings/organization/api-keys>. Create a
   secret key for the project you use with the tunnel and paste it in the
   terminal. Input is hidden: nothing appears while you paste. This key
   authenticates `tunnel-client` to OpenAI; it is **not** the RepoRelay
   bridge secret.

Creating or editing a tunnel needs the **Tunnels Read + Manage** permission;
running `tunnel-client` or selecting the tunnel needs **Tunnels Read + Use**.
These are organization-level permissions granted by your org owner or RBAC
admin. Follow the current
[OpenAI Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
for the exact UI and permission details.

When the wizard finishes, you should see:

```text
Testing connection...
✓ OpenAI runtime credential
✓ RepoRelay reachable
✓ Bridge authentication

Setup complete.

Next:
  reporelay tunnel run
```

These checks are genuine: setup validates the runtime API key against the
OpenAI control plane (the same read-only tunnel lookup `tunnel-client` performs
at startup) and verifies the bridge secret against the RepoRelay that is
actually running. A wrong, expired, or mis-pasted key is caught here with a
clear message &mdash; not after `tunnel run` starts.

If your RepoRelay runs on a custom port (for example `--port 7677`),
quickstart already recorded the live endpoint and setup follows it
automatically &mdash; no extra flags needed.

Useful options:

- `reporelay tunnel setup --no-open` — do not launch the browser (headless,
  SSH, or CI); the URLs are still printed.
- `reporelay tunnel setup --replace-tunnel` — prompt for a n