Module codex_integration 

OpenAI Codex integration for sqz.

Codex is OpenAI’s terminal coding agent (openai/codex). It does not expose a stable per-tool-call hook like Claude Code’s PreToolUse — the only event hook documented at the time of writing is notify, which fires at the END of a turn (once per user message) and so is useless for compressing tool output before the model sees it. An experimental features.codex_hooks flag is mentioned in the config reference but described as “under development; off by default” and the public hooks.json schema is not documented enough to target safely. See https://developers.openai.com/codex/config-reference.

What Codex DOES expose reliably today:

1. MCP servers via ~/.codex/config.toml under [mcp_servers.<id>]. The TOML key is mcp_servers (snake_case), NOT mcpServers (camelCase) as in JSON-based tools. See https://github.com/openai/codex/blob/main/docs/config.md.

2. AGENTS.md — project-level markdown instructions Codex reads at session start. It’s the Codex analogue of CLAUDE.md and .cursor/rules/*.mdc. A single AGENTS.md is the cross-tool convention (Codex, GitHub Copilot, Cursor, Windsurf, Amp, Devin all read it). See https://agentsmd.io.

3. The shell hook installed by sqz init — works transparently because Codex runs bash via its sandboxed exec tool and sees the compressed stdout automatically. No Codex-specific wiring needed.

This module implements (1) and (2). Guidance-file approach for (2) mirrors how RTK handles the same “no programmatic hook” problem with Codex — see https://github.com/rtk-ai/rtk/blob/master/hooks/codex/README.md.

Functions

agents_md_guidance_block

Build the markdown block that sqz appends to AGENTS.md.

agents_md_path

Return the path where Codex reads project-level instructions.

codex_config_path

Return the location of Codex’s user-level config.toml.

install_agents_md_guidance

Install sqz’s guidance block into AGENTS.md at project_dir.

install_codex_mcp_config

Merge sqz’s MCP server entry into Codex’s user-level config.toml.

remove_agents_md_guidance

Remove sqz’s guidance block from AGENTS.md.

remove_codex_mcp_config

Remove sqz’s MCP entry from Codex’s user-level config.toml.