RepoRelay

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

✓ inspect files          open_workspace, list_files, read_file
✓ find instructions      list_files with instructionsOnly
✓ search the repository  search_files
✓ write to three predetermined handoff targets
                         write_next_task, write_review, update_handoff_state

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

The **Secure MCP Tunnel** is created and configured in OpenAI Platform. The
**ChatGPT integration** that uses the tunnel is added **inside ChatGPT** — not
on the Platform page where you created the tunnel. If you already have a
tunnel and are wondering "where do I actually add RepoRelay to ChatGPT?", that
is step 6 below, inside ChatGPT itself.

> **Path examples.** Always quote the repository path:
>
> ```bash
> # macOS / Linux
> reporelay quickstart "$HOME/Projects/my-app"
> ```
>
> ```powershell
> # Windows PowerShell — keep the backslashes
> reporelay quickstart "C:\Users\you\Projects\my-app"
> ```
>
> `C:\Users\you\Projects\my-app` is correct. `C:Users\you\Projects\my-app` is
> not — the backslashes matter.

### 1. Install RepoRelay

npm is the supported and tested installer. Check the install:

If `reporelay` cannot be found (`command not found` on macOS/Linux, `is not
recognized` on Windows), see [Troubleshooting](#troubleshooting).

### 2. Start RepoRelay on one repository

Replace the path with the repository you want to expose (Windows example:
`reporelay quickstart "C:\Projects\my-app"`). Keep this terminal open.

**No path? The current directory is only a default.** If you omit the
repository path, `quickstart` uses the directory you are standing in and says
so in its summary. Only this default depends on the current directory —
`reporelay tunnel setup`, `tunnel doctor`, and `tunnel run` read stored
per-user configuration and work from any directory. The tunnel does not need
to be started from the repository directory.

You should see:

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:

Using read-only mode instead (`--no-handoff-writes`, the recommended starting
mode for personal ChatGPT workspaces that expose developer mode and Tunnel)?
RepoRelay exposes the 4 read/search tools and creates
none of these files. See [Read-only mode](#read-only-mode---no-handoff-writes).

**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:

You should see:

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. If you started quickstart with `--no-handoff-writes`, add the same
flag to the audit command.

### 4. Run RepoRelay tunnel setup

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

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

You provide exactly two things, both in OpenAI Platform:

1. **Your Secure MCP Tunnel ID** — the wizard opens
    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
   . 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:

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 — 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 — 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 new tunnel ID.
- `reporelay tunnel setup --replace-runtime-key` — prompt for a new runtime
  API key.
- `reporelay tunnel setup --tunnel-client-path "/path/to/tunnel-client"`
  (Windows: `tunnel-client.exe`) — **advanced override** for unusual
  environments; RepoRelay does not verify or manage a custom binary.

Re-running `reporelay tunnel setup` reuses your existing verified client,
tunnel ID, and stored key, and re-tests the connection without asking for
anything again.

### 5. Run the tunnel

Keep this window open alongside the RepoRelay quickstart window. Stop it with
Ctrl+C when you are done.

If the connection ever stops working, `reporelay tunnel doctor` remains
available as a standalone troubleshooting command (expect `Ready.` when
everything is healthy; add `--verbose` for redacted diagnostics).

### 6. Add RepoRelay to ChatGPT

This step happens **inside ChatGPT** — not on the OpenAI Platform page where
you created the tunnel.

Naming note: the current ChatGPT UI may have you enter through **Plugins**,
while OpenAI documentation may still refer to the underlying integration as an
**App** or **custom MCP app**. This guide just says "the RepoRelay
integration." See the current
[ChatGPT developer-mode and MCP apps guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)
when labels move.

Follow this sequence:

1. Enable **Developer Mode** in ChatGPT settings, or ask your workspace
   administrator for access. The exact location of the setting may vary by
   plan or workspace as OpenAI updates the interface.
2. Create the custom MCP app.
3. Choose the **Tunnel** connection.
4. Select the RepoRelay/OpenAI Secure MCP Tunnel.
5. When ChatGPT asks for authentication, select **No authentication**.
6. Save or create the integration.
7. Run **Scan Tools**.
8. Verify the expected RepoRelay tools appear.
9. Start a new chat and select the RepoRelay integration.

> **Authentication: No authentication.** RepoRelay already authenticates the
> local bridge through the protected `X-RepoRelay-Bridge-Secret` used by the
> tunnel. Do not configure OAuth or another ChatGPT-side authentication method.

Never paste `127.0.0.1`, `localhost`, the RepoRelay bridge secret, or an OpenAI
runtime API key into ChatGPT. The tunnel connection does all the networking.

### 7. Scan and verify the RepoRelay tools

In the ChatGPT integration flow, run **Scan Tools** and confirm that the tool
count matches your mode.

**Read-only mode (`--no-handoff-writes`) — exactly 4 tools:**

**Normal handoff mode — exactly 7 tools** (the four above, plus):

A different count usually means the other mode is running. If Scan Tools shows
shell, Git, process execution, generic file editing, delete, patching, or any
other unexpected capability, **stop and investigate** before using the
integration — run `reporelay audit "" --json` and confirm the tool
list.

### 8. Test it

Start a new chat, select the RepoRelay integration, and try:

Then test the boundary:

The second request should be blocked.

## You're connected — now what?

You now have ChatGPT reviewing your repository through a verified security
boundary. Useful prompts:

// Code block

// Code block

RepoRelay handles that request through the existing `list_files` tool with
`instructionsOnly: true`. This recursively discovers recognized instruction
files without adding a broader filename-glob tool or changing the four-tool
read-only surface.

## ChatGPT ↔ coding-agent handoff

The normal RepoRelay setup lets ChatGPT plan and review while a separate local
coding agent (Codex, Claude, or another) does the implementation. RepoRelay
coordinates them through a small `.ai-handoff` workspace:

Conceptually:

`STATE.json` coordinates the cycle. RepoRelay itself **does not run Codex or
Claude** — they are separate local applications you start yourself. The
handoff files are just a structured place to hand work back and forth.

ChatGPT can only write `NEXT_TASK.md`, `REVIEW.md`, and `STATE.json`. The
implementer-owned `RESULT.md` is never writable by ChatGPT.

See [docs/handoff-cycle.md](docs/handoff-cycle.md) for the detailed protocol
and [examples/](examples/) for reviewer and implementer prompts.

## Daily use

After the one-time setup, do not recreate the tunnel or the ChatGPT
integration. Each day:

1. Start RepoRelay:

2. Start the tunnel (in a second window):

3. Open ChatGPT, start a new chat, and select the existing RepoRelay
   integration.

Both commands can be run from any directory: quickstart takes the repository
path explicitly, and the tunnel reads its stored per-user configuration.

Keep both windows open while you use the integration. If the connection stops
working, run `reporelay tunnel doctor` again.

## Switch repositories

**RepoRelay exposes one repository at a time.**

1. Press **Ctrl+C** in the RepoRelay terminal.
2. Start RepoRelay for the new repository:

3. Keep `tunnel-client` running. It reconnects to the restarted RepoRelay
   automatically (same port and protected bridge-secret file). If you used a
   different port, the managed tunnel follows it automatically.
4. Start a new ChatGPT conversation and select the RepoRelay integration.
5. Ask ChatGPT to open the new repository.

Do not rescan tools just because the approved repository changed. Rescan only
if the tool definitions changed or ChatGPT asks you to.

## Troubleshooting

| You see | What to do |
| --- | --- |
| `'node' is not recognized` / `node: command not found` | Node.js is not installed, or the terminal was opened before the install finished. Install Node.js from , close and reopen the terminal, and check `node --version`. |
| `RepoRelay requires Node.js >=22.19 and `. RepoRelay never kills processes for you. |
| Quickstart stops about an existing `AGENTS.md` | The repository already has an `AGENTS.md` without the RepoRelay marker. RepoRelay will not overwrite it. Review the file first; if you want RepoRelay to preserve it and append the marked handoff instructions, rerun `reporelay quickstart "..." --append-agent-instructions`. |
| `tunnel-client` missing | Rerun `reporelay tunnel setup`; it re-downloads and verifies the managed client. |
| Invalid tunnel ID | The ID must look like `tunnel_` followed by 32 hex characters. Copy it again from Platform tunnel settings. |
| Runtime credential rejected | The runtime API key or tunnel context was not accepted. Check that the tunnel is associated with the target ChatGPT workspace (not only a Platform organization), that the key belongs to the same OpenAI organization/project as the tunnel, and that your account has **Tunnels Read + Use**. Rerun `reporelay tunnel setup --replace-runtime-key`. |
| Control plane unreachable | RepoRelay could not contact OpenAI to validate the credential. Check your internet connection, then rerun `reporelay tunnel doctor`. |
| Tunnel doctor cannot reach MCP | Keep the RepoRelay quickstart window running on the configured port, then rerun `reporelay tunnel doctor`. |
| Bridge authentication failure | Do not paste a secret. Confirm quickstart is using the canonical bridge-secret file, then rerun `reporelay tunnel setup`. |
| ChatGPT cannot see the tunnel | Check that the tunnel is associated with the target ChatGPT workspace (not only a Platform organization) and that you have tunnel-use permission. |
| Scan Tools returns zero tools | Keep both the RepoRelay and tunnel windows open, confirm `reporelay tunnel doctor` reports `Ready.`, then rescan in a **new** chat with the RepoRelay integration selected. |
| Scan Tools shows unexpected tools | Stop and investigate before using the integration: run `reporelay audit "" --json` and confirm the expected list — 4 tools in read-only mode, 7 with handoff writes. |
| RepoRelay window was closed | RepoRelay stopped. Restart it with `reporelay quickstart ""`, then try again in a new chat. |
| Tunnel window was closed | `tunnel-client` stopped. Restart it with `reporelay tunnel run`, then try again in a new chat. |
| Custom port mismatch | Confirm the RepoRelay quickstart port matches what `reporelay tunnel doctor` reports as the local MCP endpoint. Quickstart records the live endpoint automatically, or set it explicitly with `reporelay tunnel setup --port `. |

For anything else, run `reporelay doctor`. It prints configuration and security
status without printing secret values.

## Read-only mode (--no-handoff-writes)

Read-only mode is the recommended starting workflow for **personal ChatGPT
workspaces where developer mode and Tunnel are available** (see
[Which mode should I use?](#which-mode-should-i-use)), and for anyone who wants
ChatGPT to **inspect only** — no handoff files, no writes at all:

In this mode RepoRelay exposes exactly four tools:

Read-only mode does **not** create `.ai-handoff`, does **not** create or modify
`AGENTS.md`, and leaves the approved repository unchanged. All containment,
authentication, and security checks still apply. Use the matching audit flag:

When you use this mode, expect **4 tools** in Scan Tools instead of 7.

## Security

RepoRelay's enforced boundary includes:

- loopback-only binding and authentication required;
- exactly one existing canonical approved root;
- sensitive paths blocked, including `.env`, VCS metadata, credential stores,
  and private-key formats;
- traversal, absolute outside-root paths, symlink/junction/reparse escapes, and
  hard-link bypasses blocked;
- bounded reads, searches, results, and handoff content;
- no shell, PowerShell, Git, process, generic write, patch, delete, artifact,
  worktree, skill, subagent, or local-agent tool;
- handoff writes limited to the three fixed pre-existing targets.

RepoRelay is a least-privilege application boundary, not an operating-system
sandbox against malicious software already running as the same local user. An
external Secure MCP Tunnel is a separate security boundary and must be secured
independently. Choose the approved repository carefully.

See [SECURITY.md](SECURITY.md) for the full security model and
`reporelay audit` documentation.

## Advanced configuration

Most users never need these. When you do:

- [Configuration](docs/configuration.md) — `REPORELAY_*` environment variables,
  bridge authentication, ports, logging, and handoff mode.
- [ChatGPT Web setup details](docs/chatgpt-web.md) — the full tunnel and app
  reference.
- [Windows operations](OPERATIONS.md) — lifecycle scripts, scheduled tasks, and
  managed Windows setup.
- [`.env.example`](.env.example) — placeholder configuration only. Never put a
  real bridge secret or tunnel credential in it.
- **Local MCP clients** — if your MCP client runs on the same computer as
  RepoRelay, you do not need the tunnel: point it at the local MCP URL printed
  by quickstart and send the `X-RepoRelay-Bridge-Secret` header loaded from the
  protected file.

For configuration and security status without printing secret values:

## Requirements and platform support

- Node.js `>=22.19 <27` (npm is included);
- Git for the clone-based install — optional if you download the ZIP instead.

The quickstart in this README works on Windows, macOS, and Linux; npm is the
supported installer. Windows 10/11 is the fully validated lifecycle and
operational platform, including the PowerShell scripts and tunnel-managed
runbook.

## Limitations

- One approved repository is exposed at a time.
- RepoRelay is not an operating-system sandbox.
- ChatGPT Web needs external OpenAI Secure MCP Tunnel infrastructure to reach a
  private local bridge.
- Windows is the fully validated lifecycle platform; other platforms do not
  have identical PowerShell/tunnel operations.
- Codex, Claude, and other coding agents are separate local applications, not
  components of RepoRelay.

## Documentation

- [ChatGPT Web setup](docs/chatgpt-web.md)
- [Security model](SECURITY.md)
- [Configuration](docs/configuration.md)
- [Windows operations](OPERATIONS.md)
- [Setup notes](docs/setup.md)
- [Handoff cycle](docs/handoff-cycle.md)
- [Handoff examples](examples/)
- [Contributing](CONTRIBUTING.md)

## License and project lineage

RepoRelay is released under the [MIT License](LICENSE). The project keeps its
required upstream attribution and does not bundle the SDKs or runtimes of
Codex, Claude, or other implementers.

## Development

// Code block