# Use Orbit Browser in Codex

Install the Git-backed beta to browse Orbit projects and start chats with tasks, documents, and notes.

Orbit Browser brings your local Orbit projects into Codex. Browse tasks, documents, scratchpad notes, links, and saved dependency findings, then open a new chat with a readable brief of the selected content.

It is available through the **Orbit Beta** Git-backed marketplace while OpenAI public directory approval is pending.

## Before you start

Use macOS with the Codex desktop app and Codex CLI installed, and a Codex version that supports local plugins. Install Orbit on the same Mac, open it, and create a workspace first. The plugin has been tested with Orbit 0.5.1.

Orbit Browser uses the runtime bundled with Orbit. You do not need the Orbit source code, Composer, Node.js, or a separate PHP installation.

## Install the beta

Run these commands in Terminal:

```sh
codex plugin marketplace add SpacemanCodesLtd/orbit-plugins --ref main
codex plugin add orbit-browser@orbit-beta
```

Restart Codex. Find **Orbit Browser** under **Orbit Beta** in Plugins, then open its app or ask Codex to browse your Orbit projects. Use a local chat on the same Mac as your Orbit workspace.

The <a href="https://github.com/SpacemanCodesLtd/orbit-plugins" target="_blank" rel="noopener noreferrer">Orbit plugins repository</a> has the latest beta version, source code, and installation details.

## Browse and share project context

1. Choose a project in Orbit Browser.
2. Open **Tasks**, **Scratchpad**, **Documents**, **Dependencies**, or **Links**.
3. Select the item you want to discuss.
4. Click **Start new chat** to open a fresh conversation with its brief.

Task, document, and scratchpad briefs include the project, title, and original content. Click the button yourself in Codex; automated clicks show a manual-click instruction.

Dependency findings reflect the last checks saved in Orbit. To refresh them, [run dependency checks in Orbit](/guide/sources/dependency-checks/), then refresh Orbit Browser.

<a href="https://media.orbitdesktop.com/orbit-browser-demo-2026-10-24.mp4" target="_blank" rel="noopener noreferrer">Watch the short Orbit Browser demo.</a>

## Understand its access

Connecting the plugin lets Codex read supported project content. Browsing loads that content through Codex, and **Start new chat** sends the selected brief into a new conversation. Your Codex account settings govern how the host handles that data; local execution does not mean AI processing stays on your Mac.

Orbit Browser is read-only. It excludes Orbit secret values and secret metadata, does not edit your workspace, and does not run dependency checks or install package updates. Keep credentials out of ordinary notes and documents. Read the <a href="https://github.com/SpacemanCodesLtd/orbit-plugins/blob/main/plugins/orbit-browser/README.md#data-and-privacy" target="_blank" rel="noopener noreferrer">plugin's data and privacy information</a> before connecting.

For an AI client that can create or update Orbit content, see [Connect an AI client with MCP](/guide/integrations/mcp/).

## Update the plugin

If you installed the beta before the repository moved to SpacemanCodesLtd, replace its marketplace source once:

```sh
codex plugin marketplace remove orbit-beta
codex plugin marketplace add SpacemanCodesLtd/orbit-plugins --ref main
codex plugin add orbit-browser@orbit-beta
```

Restart Codex afterwards. Your Orbit workspace is unchanged. For later updates, run both commands below, then restart Codex:

```sh
codex plugin marketplace upgrade orbit-beta
codex plugin add orbit-browser@orbit-beta
```

## Troubleshoot startup

If Terminal cannot find `codex`, install or enable the Codex CLI before running the commands. If your version does not recognise the plugin commands, update Codex.

If the plugin cannot find Orbit, install the app in `/Applications` or `~/Applications`. If it cannot find a workspace, open Orbit and create one first. If it reports missing MCP Apps support, update Orbit. Nonstandard app and workspace locations are covered in the repository's installation instructions.

For help, [contact Orbit support](/contact/) or <a href="https://github.com/SpacemanCodesLtd/orbit-plugins/issues" target="_blank" rel="noopener noreferrer">report a beta issue</a>. Remove private project content from screenshots and logs before posting.

## Remove the plugin

```sh
codex plugin remove orbit-browser@orbit-beta
codex plugin marketplace remove orbit-beta
```

Restart Codex afterwards. Removing the plugin leaves your Orbit workspace intact; its runtime caches may remain on your Mac.