# Connect a repository

<p class="lede">Connect your project folder, restart your agent when needed, then ask it to read your Starplex project.</p>

## Before you start

[Install the CLI](/install), [sign in](/sign-in), and open a terminal in the repository you want to use. You'll need a Starplex project connected to that repository, and Claude Code, Codex or OpenCode installed.

## Connect

<ol class="steps">
<li>
<h3>Write the relay entries</h3>

```sh frame="terminal"
starplex setup-mcp
```

<p>Run this in the repository every time you connect a machine, including when relay entries are already committed. It writes entries for Claude Code, Codex and OpenCode, checks your sign-in, and reports what still needs attention.</p>
<p class="result">Read the result for each app. Follow any instructions to remove old user-level entries or resolve conflicting settings.</p>
<details class="trouble"><summary>Setup reports a conflict</summary><div class="body"><p>Read the named file and conflicting entry before changing it. Preserve unrelated settings. If you need help, share the conflict report with your agent.</p></div></details>
</li>
<li>
<h3>Restart your coding agent when told</h3>
<p>Use a fresh window or chat after changing the relay configuration. Keep the agent in this repository so it reads this folder's configuration.</p>
<p class="result">The agent can see its Starplex tools.</p>
</li>
<li>
<h3>Ask your agent to read the project</h3>
<p>Give it your project slug and ask it to read that project through its own Starplex tools. For example:</p>

```text
Read my Starplex project using your Starplex tools and tell me its name
and connected repositories. Ask me for the project slug if you need it.
```

<p class="result">You're connected when the agent reads the right project through its own tools. A successful terminal command alone isn't this check.</p>
<details class="trouble"><summary>The agent can't see the tools</summary><div class="body"><p>Run setup again in the same folder and read the per-app report. Follow its restart instructions, then try the project read in a fresh chat.</p></div></details>
</li>
</ol>

## Verify the connection

Run `starplex setup-mcp` again after the project read. Its per-app report distinguishes a relay that has started from an agent that has read a project of this folder. Check the app you actually used.