Codex Bridge

English | 中文

codex-bridge is a desktop-only plugin that connects your local vault to Codex. Its primary workflow is a localhost MCP endpoint that lets Codex search, read, and write notes without hardcoding a vault path. It also provides file-based bridge commands and optional AI summarization.

Tags: obsidian-plugin mcp codex local-first markdown notes ai-summary

Quick Links

• Features
• Install
• Local MCP server
• MCP tools
• AI summarization
• Development

Features

• Export active-note context for Codex
• Create request files from the active note
• Append the latest bridge reply back into the active note
• Create a new note from the latest bridge reply
• Summarize selected text or the active note into Codex/YYYY-MM-DD.md
• Deduplicate summaries with an MD5 hash marker
• Auto-tag summaries with #coding, #tiktok, #business, or #ai
• Switch plugin UI between Chinese and English
• Start a local MCP HTTP server bound to 127.0.0.1

Install

Manual Install

1. Download or clone this repository.
2. Create the plugin directory inside your Obsidian vault:

mkdir -p "/path/to/your/vault/.obsidian/plugins/codex-bridge"

3. Copy these files into that directory:

main.js
manifest.json
styles.css

4. Restart Obsidian.
5. Open Settings -> Community plugins.
6. Enable Codex Bridge.

Expected layout:

your-vault/
  .obsidian/
    plugins/
      codex-bridge/
        main.js
        manifest.json
        styles.css

Usage

Open the Obsidian command palette and search for Codex Bridge.

Common commands:

• Export active note context
  • Exports the current note context to _codex_bridge/context/
• Create Codex request from active note
  • Creates a request file based on the active note
• Append latest bridge reply to active note
  • Appends the newest Markdown reply from _codex_bridge/replies/
• Create note from latest bridge reply
  • Creates a new note from the newest reply
• Open bridge index
  • Opens the bridge folder README
• AI summarize selection/current note to daily note
  • Summarizes selected text first; if there is no selection, summarizes the active note

Local MCP Server

The plugin can start a desktop-only local MCP HTTP server. It listens on 127.0.0.1 and requires bearer-token authorization for every /mcp request.

Recommended pairing:

• Install this plugin in Obsidian desktop.
• Install the obsidian-connect skill in Codex.
• This plugin exposes the current vault through a local MCP endpoint.
• The skill uses MCP tools to search, read, and write notes.

This does not make your vault available to hosted or mobile AI clients. 127.0.0.1 is only visible on the same machine.

Enable it in Settings -> Codex Bridge:

1. Turn on Enable local MCP server.
2. Keep the default MCP port of 8765, unless you need another port.
3. Keep or regenerate the MCP token.
4. Click Copy MCP config when a local MCP client needs setup details.

Health check:

GET http://127.0.0.1:8765/health

MCP JSON-RPC endpoint:

POST http://127.0.0.1:8765/mcp
Authorization: Bearer <token>
Content-Type: application/json

Copied MCP config shape:

{
  "name": "codex-bridge",
  "transport": "streamable-http-json-rpc",
  "endpoint": "http://127.0.0.1:8765/mcp",
  "url": "http://127.0.0.1:8765/mcp",
  "health": "http://127.0.0.1:8765/health",
  "headers": {
    "Authorization": "Bearer <token>"
  },
  "tools": ["search_notes", "read_note", "write_note", "append_note", "list_recent_notes", "save_chat_summary"],
  "codexEnv": {
    "OBSIDIAN_MCP_PORT": "8765",
    "OBSIDIAN_MCP_TOKEN": "<token>"
  }
}

If your MCP client only supports stdio, use the included proxy:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "node",
      "args": ["/path/to/codex-bridge/codex/obsidian-mcp-proxy.js"],
      "env": {
        "OBSIDIAN_MCP_PORT": "8765",
        "OBSIDIAN_MCP_TOKEN": "<token>"
      }
    }
  }
}

MCP Tools

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "query": "obsidian",
      "limit": 10
    }
  }
}

AI Summarization

AI summarization is optional. You do not need an API key for local file bridge workflows or the local MCP server.

To enable summarization:

1. Open Settings -> Codex Bridge.
2. Set AI API key.
3. Set AI base URL, default https://api.openai.com/v1.
4. Set AI model, default gpt-4o-mini.
5. Choose AI API mode.

Recommended modes:

Summary output uses:

## Question
...

## Key Takeaways
...

## Action Steps
...

## Tags
#xxx #xxx

Language

Open Settings -> Codex Bridge, then choose English or 中文.

New installs default to English for the Obsidian community plugin directory. You can switch to Chinese at any time.

Language affects:

• Settings text
• Obsidian notices
• Command palette labels
• Exported context headings
• Generated bridge request headings
• AI summary prompt and summary headings

Command names are registered when Obsidian loads the plugin. Reload the plugin or restart Obsidian after changing language.

Security

• The MCP server binds to 127.0.0.1 only.
• All /mcp requests require a bearer token.
• Do not share your MCP token with untrusted software.
• Do not expose the local endpoint to the public internet without a proper authentication and threat model.
• Do not commit Obsidian-generated data.json, API keys, tokens, or personal vault paths.

Bridge Folder

Default folder:

_codex_bridge/
  context/
  requests/
  replies/
  imported/

You can write Codex replies into replies/, then import them back into Obsidian with the plugin commands.

Development

This repository includes the Obsidian-loadable main.js and matching main.ts source.

When changing plugin logic, update main.ts first and keep shipped main.js in sync.

Minimum Obsidian version: 1.5.0

Release

For a release, create a GitHub Release matching manifest.json, for example 0.6.0, and upload:

• main.js
• manifest.json
• styles.css

Keep these files at repository root:

• README.md
• README_zh.md
• LICENSE
• versions.json

Companion Project

For Codex-side usage, install the companion obsidian-connect skill. The skill uses this plugin's MCP endpoint and does not need a hardcoded vault path.