https://github.com/yaroslavyaroslav/CodexSublime
Sublime Text frontend for OpenAI Codex
https://github.com/yaroslavyaroslav/CodexSublime
Last synced: 9 months ago
JSON representation
Sublime Text frontend for OpenAI Codex
- Host: GitHub
- URL: https://github.com/yaroslavyaroslav/CodexSublime
- Owner: yaroslavyaroslav
- License: mit
- Created: 2025-07-11T12:46:13.000Z (11 months ago)
- Default Branch: develop
- Last Pushed: 2025-09-17T10:47:01.000Z (9 months ago)
- Last Synced: 2025-09-17T11:36:38.649Z (9 months ago)
- Language: Python
- Size: 500 KB
- Stars: 15
- Watchers: 3
- Forks: 7
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome - yaroslavyaroslav/CodexSublime - Sublime Text frontend for OpenAI Codex (Python)
README
# Codex Sublime Text plug-in
Chat with the [Codex CLI](https://github.com/openai/codex) directly from Sublime Text.
## Upgrade Notes
- API token setting: This package expects your OpenAI API token in the `token` setting and exports it to the environment variable named by `env_key` (default: `OPENAI_API_KEY`). If you previously used another package with a different setting name, please add `"token": "sk-..."` to your Codex settings or set the corresponding environment variable.
- Markdown and folding: The transcript and input panels now use a bundled Markdown syntax for improved headings and section folding. You can auto‑fold sections by header via `fold_sections` in project or global Codex settings.
The plug-in spins up a `codex proto` subprocess, shows the conversation in a
Markdown panel and lets you execute three simple commands from the Command
Palette.
---
## Features
- Full Codex capabilities
- Assistant-to-Bash interaction
- Sandboxing (on macOS and Linux)
- Model and provider selection
- MCP support (via `~/.codex/config.toml`)[^1]
- Deep Sublime Text integration
- Multiline input field uses Markdown
- Selected text is auto-copied into the message with syntax applied
- Outputs to either the output panel or a separate tab
- Symbol list included in answers
- Works out of the box[^2].
### Installation
1. **Install the Codex CLI** (the plug-in talks to the CLI, it is **not** bundled).
```bash
npm i -g @openai/codex
```
On Windows you can use
```bash
winget install OpenAI.Codex
```
By default the plug-in uses "which(codex)"
If yours lives somewhere else, set the `codex_path` setting (see below). It
accepts either a single string (e.g. `"codex.exe"` when Codex is installed natively
on Windows) or an array of strings – e.g.:
```jsonc
{
"codex_path": ["wsl", "-e", "codex"],
}
```
2. Plugin installation
1. With Package Control
`Package Control: Install Package` → **Codex**
2. Manual
Clone / download into your `Packages` folder (e.g. `~/Library/Application Support/Sublime Text/Packages/Codex`).
3. Optionally create an OpenAI token and tell the plug-in about it.
*Open the menu* → **Preferences › Package Settings › Codex** and put your
key into the generated `Codex.sublime-settings` file:
```jsonc
{
"token": "sk-…"
// exported to this env var for the Codex CLI
"env_key": "OPENAI_API_KEY"
}
```
That’s it – hit ⌘⇧P / Ctrl ⇧ P, type *Codex*, select one of
the commands and start chatting.
---
## Commands (⌘⇧P)
• **Codex: Prompt** – open a small Markdown panel, type a prompt, hit *Super+Enter*.
• **Codex: Open Transcript** – open the conversation buffer in a normal tab.
• **Codex: Reset Chat** – stop the Codex subprocess, clear the transcript and
invalidate the stored `session_id` so the next prompt starts a brand-new
session.
---
## Per-project configuration
Every Sublime project can override Codex settings under the usual `settings`
section. Example:
```jsonc
{
"folders": [{ "path": "." }],
"settings": {
"codex": {
// will be filled automatically – delete or set null to reset
"session_id": null,
// model & provider options
"model": "o3",
"provider_name": "openai",
"base_url": "https://api.openai.com/v1",
"wire_api": "responses",
"approval_policy": "on-failure",
// sandbox
"sandbox_mode": "read-only",
"permissions": [
// additional writable paths (project folders are added automatically)
"/Users/me/tmp-extra"
]
,
// Auto-fold specific sections in the transcript by their header
// name (case-insensitive). You can pass a string or a list.
// Example: fold the model's internal reasoning block
// (rendered as "## agent_reasoning").
"fold_sections": ["agent_reasoning"]
}
}
}
```
---
## Writable paths passed to Codex
The plug-in constructs the `sandbox_policy.permissions` list for each session:
1. `/private/tmp`
2. **`cwd`** – the first project folder (or the current working directory if
there is none)
3. **All folders** listed in the Sublime project (visible in the sidebar)
4. Any extra paths you add via `settings.codex.permissions`
Those paths are sent to the CLI unchanged; Codex is free to read/write inside
them depending on the selected `sandbox_mode`.
---
## Default configuration sent to the CLI
The first thing the bridge does is send a `configure_session` message:
```jsonc
{
"id": "",
"op": {
"type": "configure_session",
// model / provider
"model": "codex-mini-latest",
"approval_policy": "on-failure",
"provider": {
"name": "openai",
"base_url": "https://api.openai.com/v1",
"wire_api": "responses",
"env_key": "OPENAI_API_KEY"
},
// sandbox
"sandbox_policy": {
"permissions": [
"disk-full-read-access",
"disk-write-cwd",
"disk-write-platform-global-temp-folder",
"disk-write-platform-user-temp-folder",
{
"disk-write-folder": {"folder": "$HOME/.cache"} // for clangd cache
}
],
"mode": "workspace-write"
},
"cwd": ""
}
}
```
All values can be overridden per-project as shown above.
Enjoy hacking with Codex inside Sublime Text! 🚀
## Code sent to the language model
The plugin only sends the code snippets that you explicitly type or select in the input panel to the language model. It never uploads your entire file, buffer, or project automatically. Local configuration (such as sandbox permissions or project folders) is used only by the CLI to enforce file I/O rules and is not included in the prompt context.
However keep in mind that since this plugin and tool it relays on is agentish, any data from within your sandbox area could be sent to a server.
## Suppressing noisy events
If the Codex backend floods the transcript with incremental updates such as
`agent_reasoning_delta`, add them to the `suppress_events` array in your
project-specific `codex` settings:
```jsonc
{
"suppress_events": ["agent_reasoning_delta"]
}
```
## Auto-folding sections
You can tell the transcript to auto‑fold certain sections by header name. The
match is case-insensitive and can be configured globally or per-project.
- Global (Preferences ▸ Package Settings ▸ Codex ▸ Settings):
```jsonc
{
// ... other settings ...
"fold_sections": ["agent_reasoning"]
}
```
- Per project (`.sublime-project` under `settings.codex`):
```jsonc
{
"settings": {
"codex": {
"fold_sections": ["agent_reasoning"]
}
}
}
```
Notes
- Folding is scope-based and targets the Markdown `meta.section` for that
header. Only the section body is folded, so the header line shows with an
inline ellipsis (row style), e.g.: `## agent_reasoning ...`.
- The fold is applied right after the section is appended. If your syntax
definition delays section scopes, the plugin waits briefly to target the
correct section.
[^1]: https://github.com/openai/codex/blob/main/codex-rs/config.md#mcp_servers
[^2]: If both requirements are met (1) `codex` is installed and (2) token in settings is provided.