Skip to content

feat: add OpenAI Codex CLI agent support#337

Open
rohithreddy1095 wants to merge 1 commit intoentireio:mainfrom
rohithreddy1095:feat/codex-cli-agent
Open

feat: add OpenAI Codex CLI agent support#337
rohithreddy1095 wants to merge 1 commit intoentireio:mainfrom
rohithreddy1095:feat/codex-cli-agent

Conversation

@rohithreddy1095
Copy link

@rohithreddy1095 rohithreddy1095 commented Feb 14, 2026

Summary

  • Adds a new agent plugin for OpenAI Codex CLI, enabling Entire to track Codex sessions alongside Claude Code and Gemini CLI
  • Implements the full Agent interface (13 methods) plus optional HookSupport, HookHandler, TranscriptAnalyzer, and TranscriptChunker interfaces
  • Follows the existing plugin architecture pattern established by claudecode and geminicli packages
  • Includes 46 unit tests across 3 test files

Motivation

Developers increasingly use multiple AI coding agents (Claude Code, Gemini CLI, Codex CLI) in the same repository. Currently Entire only tracks Claude Code and Gemini CLI sessions. This PR adds Codex CLI support so that all three agents' sessions are tracked with unified checkpoint creation.

Implementation Details

New Files

File Purpose
codexcli/types.go Codex-specific types: JSONL event types, notify payload struct, transcript line types, file modification heuristics
codexcli/codex.go Full Agent interface with init() self-registration, session resolution via date-based directory tree, JSONL transcript I/O
codexcli/hooks.go Hook install/uninstall — manages notify array in ~/.codex/config.toml (TOML string manipulation)
codexcli/transcript.go JSONL parsing with 10MB scanner buffer, user/assistant message extraction, heuristic file modification detection from exec_command calls, token usage calculation
codexcli/codex_test.go Unit tests for Agent interface methods and hook input parsing (12 tests)
codexcli/hooks_test.go Unit tests for hook install/uninstall and TOML config manipulation (12 tests)
codexcli/transcript_test.go Unit tests for transcript parsing, file extraction, token usage, and command detection (22 tests)
hooks_codexcli_handlers.go handleCodexTurnComplete() — session dir setup, metadata extraction, strategy-based commit

Modified Files

File Change
registry.go Added AgentNameCodex and AgentTypeCodex constants
hook_registry.go Registered turn-complete handler + codexcli import
hooks_cmd.go Added blank import for agent registration
summarize/summarize.go Added AgentTypeCodex to exhaustive switch
setup.go Added Codex hook removal in removeAgentHooks()

Key Design Decisions

  • Single hook: Codex only supports notify (agent-turn-complete), so the handler combines state capture + commit in one pass (unlike Claude's 7 hooks or Gemini's 10 hooks)
  • TOML config: Codex uses ~/.codex/config.toml with a notify array, handled via string manipulation (no new TOML dependency)
  • File modification detection: Codex uses exec_command with shell commands instead of structured tools. Detection is heuristic-based (handles apply_patch diffs, cat >, sed -i, etc.)
  • Session format: JSONL at ~/.codex/sessions/<year>/<month>/<day>/rollout-<date>-<uuid>.jsonl

Test plan

  • go build ./... passes
  • go vet ./... passes
  • golangci-lint passes (0 issues across entire project)
  • 46 unit tests pass across codex_test.go, hooks_test.go, transcript_test.go
  • gofmt clean
  • entire enable --agent codex installs notify hook in ~/.codex/config.toml
  • entire enable --agent codex is idempotent (detects already installed)
  • entire disable --uninstall removes Codex notify hook and preserves other config
  • Codex turn-complete fires and creates checkpoint with metadata
  • Existing Claude Code and Gemini CLI hooks continue working (no regressions)

@rohithreddy1095 rohithreddy1095 requested a review from a team as a code owner February 14, 2026 17:45
Implement full agent plugin for OpenAI Codex CLI, including:
- Agent interface implementation (codex.go) with session management
- Hook support via Codex notify config in ~/.codex/config.toml
- JSONL transcript parsing with user/assistant/tool extraction
- Token usage calculation from cumulative token_count events
- Modified file detection via exec_command heuristics
- Turn-complete hook handler for checkpoint creation
- Comprehensive unit tests (46 tests across 3 test files)
- Exhaustive switch coverage for AgentTypeCodex in summarize
- Codex hook removal in removeAgentHooks (setup.go)

Codex CLI uses a single notify hook (agent-turn-complete) rather than
separate before/after hooks, so the handler combines state capture
and commit in one pass.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant