Use Obris in the Codex CLI.

The plugin's goal is to sync your Obris knowledge to disk through the obris CLI, where Codex can read your topics as files. That's faster than calling a server every time, and it leaves Codex more room to focus on what you actually asked. The bundled MCP server keeps your knowledge reachable when Codex doesn't have filesystem access.

Provides:

• MCP server: List topics, read items, and save knowledge from any Codex CLI session.
• @obris-sync skill: Sync a topic to a local directory (pulls remote items, pushes local edits, bulk-uploads via --add-all, manages exclude/include rules per directory).
• @obris-add skill: Push a single local file into a synced topic.
• @obris-link skill: Relink a renamed file to its remote item.
• @obris-unlink skill: Stop syncing a file without deleting either side.
• @obris-auth skill: Set up Obris CLI authentication.

Common workflows

• Bootstrap a new directory into a topic. Find or create the topic, then obris sync -p <dir> -t <id> --add-all. Subdirs become subtopics; files in .env, .ssh/, .aws/, .git/ etc. are skipped by default.
• Pull a topic down to inspect its files. obris sync -p <dir> -t <id> with no --add-all. Pulls every item; doesn't upload local files.
• Keep a working directory synced. Just obris sync -p <dir> with no flags. It picks up local edits and remote changes, surfaces conflicts, and reports new untracked files without uploading them.
• Override a default exclusion (e.g., a .env.example you actually do want synced). obris sync include .env.example -p <dir>. Last-call-wins; the inverse is obris sync exclude.

Install the plugin

1. Register the marketplace from a terminal:

   codex plugin marketplace add obris-dev/obris-codex-plugin

2. Start a Codex session:

   codex

3. Inside Codex, run /plugins, tab to Obris, and select Install plugin.

For more on what codex plugin marketplace add does, see OpenAI's Add a marketplace from the CLI docs.

Plugin install runs through the Codex CLI, but once installed the plugin shows up in the Codex desktop app too. No separate install needed there. The IDE extensions don't surface plugin management yet; if you use Codex through one of those, connect Obris over MCP via an MCP connector instead.

Enable the MCP server (one-time auth)

Installing the plugin registers Obris's MCP server with Codex, but Codex is not yet signed in to your Obris account. The first time you ask Codex to do something that hits an Obris tool, it will prompt you to sign in.

1. In a Codex CLI session, ask anything that needs Obris. For example, "list my Obris topics."
2. Codex prompts you to sign in to Obris and surfaces a sign-in URL. Open it in your browser and authorize Codex to access your Obris account.
3. Return to the session. The original request continues, and every future Obris tool call uses your account automatically.

Sign-in is per device. A second CLI workstation walks through the same one-time flow.

CLI authentication

The sync, add, and link skills shell out to the bundled obris CLI. The first time the agent runs an obris command, the @obris-auth skill walks you through a two-step browser sign-in. No API keys to copy.

The MCP server works without ever invoking the CLI. The CLI is only involved for the disk-level sync commands.

Invoking skills

Codex picks up skills automatically when their description matches what you're asking for. To invoke one explicitly, type @ in a Codex session and select the skill by name (@obris-sync, @obris-add, @obris-link, @obris-auth).

Links

• Obris
• Plugin documentation
• Obris CLI on PyPI
• CLI documentation
• Codex plugin docs (OpenAI)
• Using Claude instead? See the Obris Claude Plugin.