Codex

A native, dockable Obsidian desktop chat for Codex CLI or Claude Code CLI, using your installed executable and existing provider login. Attach notes, selections, text files, and images; stream Markdown; handle tool approvals; resume saved conversations; and export answers to notes.

This unofficial community integration is independent of OpenAI, Anthropic, and Obsidian. It does not embed either provider's entire IDE extension.

한국어 안내 · Verification record · Third-party notices

Install or upgrade

Requires Obsidian desktop 1.8+ and at least one installed, authenticated CLI. Tested with Codex CLI 0.164.0, Claude Code 2.1.312, and the pinned Claude Agent SDK 0.3.312. Codex app-server uses experimental APIs; CLI/SDK changes may require a compatible plugin update.

1. Check codex --version or claude --version in a terminal. Complete your provider's normal terminal login if needed. No API key or password is entered in the plugin.
2. Install from the Obsidian Community plugins directory once the plugin is published, or download main.js, manifest.json, and styles.css from the matching GitHub release into <vault>/.obsidian/plugins/codex-agent-chat/.
3. Enable Settings → Community plugins → Codex. If upgrading from the earlier manual installation, disable the old Codex plugin first. The new plugin copies the old settings on first launch; the original settings remain in place.
4. Open Codex: Open chat. The model · effort control opens the reasoning selector; click the model name inside it to choose a provider or model. The adjacent Work/Plan · permissions picker contains mode and permissions. Read-only is the default for a newly selected provider.

Each provider keeps its own model, effort, permission mode, and last conversation. Switching clears the composer and attachments and restores the selected provider's history. Finish or stop a running turn before switching. Existing Codex settings/history remain available.

Executable paths and the working-folder override are saved separately for macOS, Windows, and Linux. When upgrading a synced vault, recognizable legacy paths are retained for their original OS; the current OS uses local CLI discovery and the current vault folder until you set its own overrides.

If a GUI app cannot find a CLI, run which codex / which claude on macOS or Linux, or where.exe codex / where.exe claude on Windows, and put the absolute executable path into Settings → Codex. Blank uses discovery for the current OS. A leading ~ expands to your home folder. Executable settings accept a path, not a shell command or arguments. A missing explicit override reports an error so a typo does not select a different installation. Discovery uses OS-specific locations: Homebrew and Codex.app on macOS, user-local/system bins on Linux, and user-local bins, npm, and the OpenAI Codex install folder on Windows. Known Windows npm codex.cmd / claude.cmd launchers resolve to their package JavaScript entry and a real Node.js executable; arbitrary shell shims are rejected with guidance. Native CLI installs do not need a separate Node.js runtime. Windows and Linux paths/launches have regression coverage; live desktop verification was performed on macOS.

To build and install from source without downloading the SDK's optional native CLI packages:

npm ci --omit=optional
npm rebuild esbuild
npm run check
node scripts/install.mjs "/absolute/path/to/your/vault"

The installer copies the runtime files and license/notices, backs up earlier plugin files outside the plugins directory, and leaves enablement and other plugins unchanged. Use a disposable vault for development. The release includes all JavaScript runtime dependencies; it needs no npm install inside your vault. The CLIs themselves are not bundled.

Context and everyday use

The header uses a pencil-in-square icon for New conversation and a clock-arrow icon for Conversation history. Hover for labels; both remain keyboard-accessible.

• + → Attach active note attaches a snapshot of the active note, including unsaved editor text.
• Select a passage → Attach selection: a direct button appears beside + while note text is selected. It supports source text, Live Preview rendered blocks, and reading view. In the editor, you can also right-click → Attach selection to chat, use + → Attach selection, or run Codex: Attach selection to chat. You can assign that command a shortcut under Settings → Hotkeys.
• Selection attachments show the source note, a line range when reliable, and an excerpt summary. Click the excerpt to inspect the exact text before sending; × removes it. Selection attaches a snapshot, not the whole note. Deselecting or selecting chat/UI text does not reuse an old note selection.
• + → Attach file or image selects a vault text file or image. PNG/JPEG/WebP/GIF images are limited to eight per message, each under 10 MiB. Codex checks model-advertised image support; Claude images are sent as typed image blocks.
• Paste a clipboard image into the chat composer to attach it. The image is saved in the vault using Obsidian's configured attachment location.
• Attached text is explicitly labeled quoted reference material, separate from your request. The transcript collapses it under Attached context. Attachments are used once and cleared after an accepted send.
• Send with Cmd+Enter / Ctrl+Enter. Stop interrupts the current provider. Codex additionally supports Steer during a turn; Claude accepts the next follow-up after the current turn finishes or is stopped, preserving the same session.
• History lists/searches sessions for the current working folder. Recent Codex turns load first with Load earlier messages for older turns. Claude history is read through the official SDK session helpers.
• Commands/tools are collapsible. Changes show tool details/diffs and buttons to open changed vault files. Claude edit displays reflect tool inputs/results, rather than a complete Git staging interface.
• ⋯ offers rename, fork, archive/restore, review, copying, note exports, account/skills/MCP inspection. Conversation copy/export includes the available full history; exporting during work captures the currently available snapshot. You can also save/copy only the latest answer.
• Claude archive/restore is a vault-local visibility preference: it hides/restores a session in this plugin and does not move or delete the CLI transcript. Codex archive uses the Codex server's archive operation.

Command-palette actions include Open chat, Show conversation history, New chat, Export conversation to note, Copy latest response, Review changes, Rename conversation, provider switching, and note/selection attachments.

The / Commands menu lists local client commands:

These commands are not a full terminal command interface. Codex skills use $skill-name; Claude skills use /skill-name. Names matching a local command above are handled by this client. Provider settings, agents, hooks, and MCP/skill installation are managed with the provider's CLI.

Permissions

The providers have different execution boundaries; the labels describe those differences.

Selecting full access/bypass requires an explicit confirmation. Controls are locked during execution, and each new turn reapplies the selected policy. File approvals show the target and proposed changes when provided. Shell approvals show the working directory and the command, with long commands collapsed under Command to run. Full request shows the original approval parameters. File and command approvals apply once, additional permissions apply for the current turn, and closing the prompt denies the request. User questions support choices, multiple selections when requested, and free text where permitted.

Claude's tool restrictions are not an OS sandbox or a guarantee that all local activity is read-only. The SDK intentionally loads the normal claude_code system prompt and user/project/local settings so your CLAUDE.md, skills, MCP configuration, and customizations work. Existing CLI hooks/settings can run their own code outside the plugin's tool guard, and manual mode honors already configured allow rules. Treat that configuration as trusted, just as when running Claude Code yourself. The plugin does not use --bare, which would bypass normal OAuth login.

The plugin does not automatically attach your whole vault. Both agents can still read files through tools according to their current permissions. This is not an attachment-only isolation boundary. Provider policies govern prompts, attachments, tool-read content, and usage data.

The plugin does not read CLI login files or save tokens/passwords. The launched CLI inherits Obsidian's process environment, including any credentials or other sensitive values present there; its own configuration, hooks, tools, and provider may use them. Its data.json stores provider preferences, CLI paths, working folder, last session IDs, and vault-local Claude archive IDs. Conversations stay in provider-managed storage unless you explicitly export Markdown notes.

The community scanner reports filesystem access and child-process execution: the plugin discovers installed executables, starts the CLI, and runs fixed-argument Git commands when you request a Claude review. The file picker enumerates vault file paths; it reads selected content when you attach it. Claude image bytes are read through Obsidian's vault API, limited to selected image files in the current vault. Copy actions write to the system clipboard. The bundled Claude SDK contains dynamic code generation, which the scanner also reports. These capabilities remain present and should not be interpreted as a complete security boundary.

Closing the panel/disabling the plugin closes its owned processes and denies pending approvals. Reopening resumes persisted history. Requests are not automatically replayed after failures/timeouts: inspect history before resending an action with an unknown outcome.

Capabilities and limits

Neither provider's full IDE UI is embedded. VS Code inline edits/diagnostics, integrated terminal, Git staging/revert/merge, cloud-task/worktree/PR management interfaces, rich MCP app widgets, voice/Realtime, remote hosts/WSL selection, and Obsidian mobile are not included. CLI/provider behavior, managed policies, and available account models may impose further limits.

Git review requires a Git working folder. Claude review supplies fixed-argument, read-only Git command output because shell execution is blocked in read-only mode. Source snapshots are bounded and labeled reference data; large diffs may be truncated. Review never enables write/shell tools to gather the snapshot.

Troubleshooting

• Login: complete normal codex login or Claude's /login flow in a terminal as the same OS user; then reconnect. No auth configuration is changed by the plugin.
• Claude reports an unknown CLI option: install a Claude Code version compatible with the pinned SDK; older versions such as 1.0.65 do not support its required options. Version 2.1.312 was used in earlier compatibility testing.
• Working folder: saved separately for each OS; blank uses your vault at its current location. Set an existing absolute folder and reconnect for another project. History uses that folder; note/file attachments still come from the current vault. Start a new conversation when changing projects.
• CLI/protocol error: use ⋯ → Reconnect after fixing executable/login/version issues. Prompts rejected before acceptance stay in the composer. For errors after acceptance, inspect the conversation before retrying; an action may already have run.
• Long attachments: total text defaults to 60,000 characters per message; settings permit 1,000–500,000. Select a smaller excerpt to use less context. A character limit does not guarantee a token budget.
• Claude blocked tool: read-only deliberately blocks shell, editing, agents, and MCP tools even when existing settings would allow them. Switch explicitly to Manual approvals for work that needs those tools.

Development

npm ci --omit=optional
npm rebuild esbuild
npm run check          # typecheck, production builds, transport/adapter/view tests
npm run dev            # watch the plugin
npm run bundle         # dist/codex-agent-chat-0.5.5.zip

npm ci --omit=optional avoids downloading Anthropic's optional native CLI packages. Rebuilding esbuild supplies its own platform build executable. The JavaScript SDK is embedded in main.js with scoped Node timers/AbortSignal for Electron; it never replaces renderer globals. No native CLI binary is embedded or silently downloaded at runtime.

• src/protocol.ts: Codex JSONL transport, process lifecycle, executable discovery, policies.
• src/claude.ts: official-SDK adapter, streaming/block reconciliation, session helpers, approvals/questions, interruption.
• src/claude-review.ts: bounded read-only Git review snapshots.
• src/claude-sdk-runtime.ts: SDK bundle entry point.
• src/session.ts, src/forms.ts: turn races, explicit context, typed form validation.
• src/main.ts: native Obsidian view/settings/dialogs and serialized provider switching.
• Tests include child-process protocol fixtures, the actual built SDK under browser-like globals with real permission control messages, adapter lifecycle/policy/session/block regressions, and happy-dom view tests for history/export/approvals/provider isolation. They require no credentials or network calls. Native/provider-backed evidence is recorded separately in VERIFICATION.md.

Official references: Codex app-server, Claude SDK permissions, Claude SDK sessions, Claude user input, Obsidian plugin development.

Plugin source: MIT. Claude runtime: third-party terms/notices. Keep license/notices with redistributed builds.