codex-translate

RU→EN translation and document cache for OpenAI Codex CLI / ChatGPT App.

codex-translate translates Cyrillic Markdown once, stores the English result in a shared cache, and lets Codex read the cached English on later tool calls. Translation is executed by the installed codex CLI in headless mode and uses the existing ChatGPT/Codex subscription. The translation tier is pinned to gpt-5.6-luna (Low):

codex exec --model gpt-5.6-luna -c model_reasoning_effort="low"

There is no direct OpenAI API client in this package. If the CLI fails, times out, or the subscription limit is exhausted, the operation fails open and the original Russian Markdown remains readable. No more expensive model is attempted.

Install

npm install -g codex-translate
codex-translate init --path
source ~/.zshrc

The initializer creates ~/.codex/translate-proxy/, installs the CLI/MCP wrappers, copies the Codex hook bundle to ~/.codex/plugins/codex-translate, and leaves existing user config intact. To register the MCP server explicitly:

codex mcp add codex-translate -- codex-translate-mcp

Quick start

cd ~/Projects/your-repo
codex-translate docs --dry-run
codex-translate docs
codex-translate agentsmd
codex-translate codexmd
codex-translate report --days 7

Keep the source of truth in AGENTS.ru.md or CODEX.ru.md; the generated English file has a SHA-256 freshness marker. CI can enforce freshness:

codex-translate agentsmd --check
codex-translate codexmd --check

Shared cache

The Codex cache lives at ~/.codex/translate-proxy/cache. Fresh entries are reused from:

• ~/.cursor/translate-proxy
• ~/.claude/translate-proxy
• ~/.gemini/translate-proxy
• ~/.codex/translate-proxy

Use CODEX_TRANSLATE_HOME to relocate the Codex home. Set CODEX_TRANSLATE_SIBLING_HOMES when a custom sibling layout is needed.

Commands

| Command | Purpose | | --- | --- | | init [--dry-run] [--path] | Create config, glossary, wrappers, hooks, plugin bundle and optional PATH entry | | doc <file> | Warm one document cache entry | | docs [path] | Batch-warm project Markdown cache | | agentsmd | Generate AGENTS.md from AGENTS.ru.md | | codexmd | Generate CODEX.md from CODEX.ru.md | | resolve <file> | Resolve a file to its cached English path | | hook-resolve | JSON stdin hook handler; always allows the original read on failure | | prompt "..." | Translate a prompt, with --en-ru for reverse direction | | agent -- "..." | Translate a prompt and run codex exec | | report [--days N] | Show cache savings and subscription translation ROI | | cache-gc [--days N] | Remove old orphaned cache entries | | backfill-costs | Backfill historical cost estimates in metrics |

Configuration

~/.codex/translate-proxy/config.yaml is generated with:

translator:
  provider: codex-cli
  model: gpt-5.6-luna (Low)
  doc_fallback_model: gpt-5.6-luna (Low)
cache:
  share_siblings: true
safety:
  fail_open: true

The claude-cli provider label used internally by @cursor-translate/core is only a compatibility seam; the spawned binary is the package's Codex shim, which invokes codex exec.

Development

npm install
npm test
npm pack --dry-run

Tests use Node's built-in test runner and do not call Codex or any API. See docs/runtime-guide.md and docs/publishing.md.

License

MIT © davlet42