lua/codex/: Core plugin modules (init.lua,config.lua,utils.lua,terminal.lua,logger.lua). Public API is ininit.lua(setup,open,toggle).plugin/codex.lua: Auto‑bootstrap of commands on startup.tests/: Headless sanity tests (minimal_init.lua,run_basic.lua,run_commands.lua).Makefile: Convenience targets for running tests.
make test: Runs headless Neovim tests (basic + commands). Equivalent to:nvim --headless -u tests/minimal_init.lua +"lua dofile(\"tests/run_basic.lua\")"nvim --headless -u tests/minimal_init.lua +"lua dofile(\"tests/run_commands.lua\")"
- Local dev: open this repo in Neovim and run
:luafile %while editing. - Real runs require Codex CLI on PATH (e.g.,
brew install codexornpm i -g @openai/codex).
- Language: Lua 5.1 (Neovim runtime). Indent 2 spaces; no tabs.
- Files: snake_case names in
lua/codex/(e.g.,utils.lua). - Exports: return module table
M; public functions use verb names (setup,open,exec). - Prefer
vim.api,vim.fn, and scheduled UI calls (vim.schedule) for safety. - Keep logs concise; use
logger.[error|warn|info|debug|trace]with a component tag.
- Tests are headless and self‑contained; no external Codex binary required (tests stub with
echo). - Add new tests under
tests/, following the current pattern (run_*.lua). - Run tests via
make test. Keep tests fast (<1s) and deterministic.
- Commits: imperative mood, scoped when useful. Example:
terminal: reuse buffer when split exists. - PRs: include a clear description, reproduction steps, and screenshots or logs (Neovim messages) when UI behavior changes.
- Link related issues; update
README.mdfor user‑visible options or commands.
- Key options in
config.lua(e.g.,bin,model,cwd_provider,terminal.*). Example:require("codex").setup({ bin = "codex", terminal = { direction = "vertical", size = 0.4 } })
- Set log level via
CODEX_LOG_LEVEL=debugorsetup({ log_level = "debug" })during development.