Obris logo

Obris Codex Plugin

Install 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.

What you get

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

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. 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 prompts 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).

Check the connection

Once installed and signed in, verify the plugin is wired up by asking Codex in a CLI session:

List my Obris topics

You should see the topics in your Obris account. If a topic is empty or new, you can also try:

What knowledge do I have in my [topic name] topic?

AI tools decide when to invoke MCP tools. If Codex does not pull from your Obris data, try mentioning Obris explicitly in your prompt, for example "Using Obris, find my knowledge about..."

Using something other than Codex? See the Obris Claude plugin, or connect Obris directly via the CLI, the MCP server, or an MCP connector.