Codex Session Manager

Linux-native Codex-compatible session manager and agent workstation.

The target is observable 1:1 feature parity with OpenAI Codex CLI/app behavior where public APIs, local configuration, and safe compatibility boundaries allow it. The second target is better long-session performance: bounded hot context, fast resume, deterministic replay, typed tool state, and a terminal UI designed for serious daily work. Interactive parity must be proven with human-emulated E2E tests for 1:1 aesthetics, satisfying animations, visual stability, and measured performance.

This is not a private binary clone. The project uses documented OpenAI APIs, public Codex behavior, public source where available, local runtime traces, and black-box compatibility tests.

Current Status

Initial foundation:

• Rust CLI and library
• local Codex doctor command
• runtime metrics parser for codex-tui.log
• initial observable parity matrix
• shell approval/risk policy foundation
• safe Codex config and feature-list inventory
• safe reference capture for local Codex help/version/features surfaces
• streaming session JSONL replay summary with malformed-line handling
• native append-only event envelope foundation
• sparse native event-log index generation for resume diagnostics
• native event-log replay state reducer for session/tool aggregates
• durable native tool status projection for approval/replay state
• native session-store foundation for creating and listing session logs
• native session-store append path for shell, PTY, and live PTY tool projections
• per-session advisory locks for cross-process native session appends
• native session fork foundation for copying a validated session prefix into a new indexed branch
• native resume-plan foundation using adjacent sparse indexes
• checkpoint-backed native resume replay using replay seeds in sparse indexes
• replay-seed compaction handoff artifacts with payload-free event references
• semantic-summary compaction handoff artifacts with payload-free event references
• schema-v5 index tracking for latest compaction handoff artifact references
• deterministic native event-log fixture generation
• repeatable native event-log benchmark report
• CI indexed-resume performance evidence gate for a deterministic 60k-event status-rich fixture over 10MB, benchmark report, resume plan, and checkpoint-backed resume replay
• typed GPT-5.5 Responses request construction
• offline Responses API SSE stream parser and accumulator
• incremental Responses API SSE decoder foundation
• mock-tested Responses HTTP transport boundary
• Responses stream to native event-log projection without raw payload retention
• persisted single-turn Responses runtime that appends user/model/failure events into native sessions with previous_response_id handoff
• persisted Responses runtime prompt assembly that injects payload-free replay-seed or semantic-summary compaction context when no previous_response_id is available
• live model run-turn CLI surface for existing native sessions with env/file API key resolution and prompt-file support
• in-memory model tool planner that maps completed exec_command function calls to typed shell requests without writing raw arguments to event logs
• scheduler bridge for starting safe model tool plans with redacted per-request spawn/pending-approval/reject/error outcomes
• model/tool turn orchestrator that runs a persisted model turn and keeps spawned scheduler tools owned and addressable through the caller
• redacted orchestrator finish-all report for explicitly draining active tools
• one-pass Responses tool-output continuation using function_call_output items keyed by model call_id with bounded redacted PTY output previews
• bounded library-level model/tool loop that can execute continuation-produced tool plans until a final no-tool response or an explicit round cap
• model run-tool-turn CLI smoke surface for one model/tool turn with explicit approval, active-tool finish before process exit, and optional --continue-after-tools or bounded --max-tool-rounds
• headless terminal grid/diff renderer foundation
• ASCII render snapshot serializer and bounded semantic diff foundation
• deterministic ANSI commit byte planner
• headless terminal workstation view foundation with snapshot-tested layouts
• named view fixtures for offline UI snapshot and E2E evidence
• offline resize-flow human-emulated E2E evidence for view fixtures
• deterministic terminal-app smoke harness with JSON/text CLI evidence
• live terminal-app driver foundation with raw-mode polling, resize checks, bracketed paste, ESC timeout, and PTY smoke coverage
• optional terminal-app prompt submission bridge into the bounded model/tool-loop runtime with redacted report events, sanitized progress frames, projected response/tool progress labels, live tool-pane start/finish updates, pending approval projection, approve/reject decision routing, pollable worker-runtime handling for resize/read-only input, deterministic fake-runtime harness coverage, bounded active-PTY poll cumulative byte-count plus recent-line live preview in the tool row, attached-stream live previews without explicit poll requests, and PTY-backed CLI coverage
• expanded command palette for composer commands, prompt submit, active-session interrupt, approval decisions, foreground active-tool controls, foreground cycling/backgrounding, bulk active-tool poll/attach/detach/close-input/backgrounding, and web-search toggle/live/cached/disabled modes plus approval-policy modes for future prompts, with Ctrl-U/Ctrl-W palette query correction and driver routing that keeps palette query bytes out of active PTY stdin
• terminal app latest-session resume selection via --resume-last
• top-level resume and fork wrappers for explicit, latest, or TTY line-picker-selected native sessions; explicit/latest forms can submit an initial prompt into the live terminal runtime, with effective config/profile/model projection, approval-policy flags, read-only/workspace-write model-tool sandbox projection, --add-dir writable-root binding with default workspace-write promotion, --cd runtime working-directory override, Responses hosted web_search projection for explicit live --search, default/configured cached search, web_search = "disabled|cached|live", legacy search feature toggles, tools.web_search context/domain/location controls, palette controls for preset and arbitrary model selection, low/medium/high/xhigh reasoning effort, low/medium/high verbosity, approval-policy mode selection, live/cached/disabled search mode, low/medium/high search context size, preset and arbitrary domain restrictions, and key/value approximate location hints, local --image projection for initial-prompt and staged first composer submissions, and --no-alt-screen inline rendering
• top-level resume --all and fork --all native-session listing when stdin is not a terminal, with --all opening a searchable line picker on a TTY; fresh exec, review, and MCP-created sessions are marked non-interactive, and resume picker/--all/--last hide them unless --include-non-interactive is set, while full-screen visual and animation polish remain open parity work
• bare exec wrapper for fresh native-session non-interactive prompts, piped stdin, prompt-plus-stdin <stdin> blocks, model override, JSONL model/tool events with a final report, strict Responses text.format output schemas, and --output-last-message
• exec resume native-session wrapper for non-interactive --last/explicit session prompts, stdin -, model override, bounded model/tool loops, JSON event streams, strict Responses text.format output schemas, and --output-last-message
• top-level review and exec review wrappers for uncommitted, base-branch, and commit diffs with custom instructions, model override, JSON reports, and --output-last-message, plus effective config/profile review model projection through -c, --enable, --disable, and exec-level --profile; exec review accepts exec-level --color, --sandbox, and --output-schema before the subcommand, validates color/sandbox, and keeps schema/sandbox inert because review has no model-planned shell tool loop; review git-repository checks are enforced, and exec review accepts observed exec-only compatibility flags including --skip-git-repo-check, --ignore-user-config, --ignore-rules, and --ephemeral transient non-persistent review sessions
• native exec and exec resume model/runtime defaults from effective $CODEX_HOME/config.toml, transient -c overrides, feature toggles, and exec profiles without mutating config files; local --image attachments are projected into Responses image input parts; git-repository checks are enforced unless --skip-git-repo-check is set; explicit --sandbox read-only and --sandbox workspace-write model-planned PTY tools run through the native bubblewrap wrapper, and --add-dir binds extra writable roots into that sandbox. When --add-dir is provided without an explicit or configured sandbox and sandbox bypass is off, native exec / exec resume promotes model-planned PTY tools to the workspace-write bubblewrap mode so the requested roots are actually writable. exec --ephemeral, exec resume --ephemeral, and exec review --ephemeral run through a transient session root that is removed after completion; resume ephemeral clones the selected source session into that root first, leaving the configured native session root unmodified. Remaining visible exec flags such as OSS/local providers are accepted with explicit blockers where native behavior is not implemented
• apply surface with hosted task diff retrieval marked blocked and a native --patch-file path backed by git apply
• help-compatible top-level login, logout, mcp-server, completion, update, sandbox, debug, cloud, exec-server, and features surfaces; mcp-server owns the safe native stdio JSON-RPC handshake, tool listing, method errors, malformed-line recovery, and model-backed codex/codex-reply calls through the native session/model runtime, with upstream-style content plus structuredContent results and explicit MCP compact-prompt persistence for replay-seed and semantic-summary compaction context injection; MCP read-only and workspace-write sandbox modes use the same native bubblewrap-backed PTY tool runtime, sandbox linux runs explicit danger/no-sandbox commands natively and uses bubblewrap for default read-only plus workspace-write sandbox modes, including custom named permissions profiles that resolve to configured sandbox modes, while --include-managed-config is accepted only when no managed source is present and full upstream [permissions] policy parity remains open, completion generates native shell completions, features list prefers live local Codex feature output, falls back to the embedded catalog offline, and overlays config/transient effective state without mutation; features enable/disable validate feature names and mutate [features] config entries, native app-server config/value/write and config/batchWrite mutate only known non-secret user config.toml keys from the safe config/read projection, debug prompt-input renders a local prompt/image input JSON slice with upstream-style image wrappers, debug models can bridge to a local upstream Codex binary for raw model catalog inspection and --bundled has a sanitized embedded fallback when upstream is unavailable, debug app-server send-message-v2 can bridge to upstream Codex for its verbose protocol transcript, loopback exec-server can bridge to upstream Codex, and private/runtime-backed surfaces return explicit blockers
• hidden execpolicy check prefix-rule evaluator for local rule files, including strictest-decision JSON output and host executable resolution
• safe native mcp list, mcp get, mcp add, and mcp remove surfaces for configured ~/.codex/config.toml MCP servers, with -c key=value read overrides, secret-bearing value redaction, and OAuth commands reported as explicit blockers
• safe native plugin inventory for cached .codex-plugin/plugin.json manifests, manifest schema validation errors, and frontmatter-only plugin skill index entries, plus help-compatible plugin marketplace command blockers
• help-compatible app-server runtime bridge to a local upstream Codex binary, native app-server --listen unix:// control-socket serving, native loopback app-server --listen ws://IP:PORT WebSocket serving with health endpoints, native app-server proxy stdio-to-control-socket transport, and native stdio/Unix-socket/WebSocket JSON-RPC bootstrap for local thread/start / thread/resume / thread/fork, thread name/git/archive metadata, async model-backed turn/start for text/image and bounded local skill/mention file input through the Responses/tool loop with transient thread/status/changed, turn/started, redacted commandExecution item/started / item/completed shells for model-planned shell tools, agent-message delta/completion notifications, and turn/completed notifications whose turn readbacks include redacted userMessage, agentMessage, and commandExecution item shells, connection-scoped turn/interrupt cancellation for active native turns, and payload-free native event logs, native command/exec for standalone argv execution with bounded buffered stdout/stderr capture, non-PTY streaming stdout/stderr notifications, streaming stdin write/close, PTY process sessions with bounded combined output deltas, PTY stdin write/close, PTY resize, connection-scoped terminate, and timeout/terminate cleanup, async model-backed thread/compact/start semantic summary compaction with deprecated thread/compacted notification compatibility and redacted contextCompaction turn item readback, thread/model/config/account/auth/MCP/hook/skill/app inventory including metadata-only user/project hook discovery from config.toml and hooks.json, initialized remote-control disabled status notifications, redacted conversation summaries, metadata-only filesystem inspection and directory listing, bounded base64 file reads and writes, bounded regular-file and recursive directory copy, bounded regular-file and recursive directory remove, directory creation, safe MCP config reload acknowledgement, connection-scoped filesystem watch registration with bounded polling fs/changed notifications, bounded fuzzy file search plus experimental-gated fuzzy-search session update/completion notifications, cached plugin list/read projection, bounded thread/shellCommand user-shell execution with command item notifications and payload-free persisted metadata, schema-declared unsafe/private mutation methods return explicit native blockers, native gitDiffToRemote HEAD/upstream diff projection, and static reference generation for app-server generate-ts and app-server generate-json-schema
• typed shell tool request/event model
• bounded non-PTY shell execution adapter with tool/event-log projection
• PTY execution foundation for non-interactive shell requests with combined output, policy-aware CLI smoke, and event-log projection
• live PTY controller library foundation for stdin writes, input close, runtime resize, kill, transient output drains, and incremental event projection
• actor-backed live PTY CLI smoke surface for scripted input, resize, drain, close, kill, and event-log replay checks
• bounded live PTY actor foundation for queued input, resize, drain, kill, finish, per-command actor replies, and incremental event-log projection
• persisted live PTY runtime bridge for appending actor starts, commands, rejections, command errors, and finishes into native session-store logs
• native tool runtime scheduler foundation for multiple persisted PTY actors, duplicate active ID rejection, and serialized session-store appends
• replayable PTY input byte-count, resize, signal, and control-action event schema
• human-emulated E2E parity requirements for UI, animation, and performance
• offline human-emulated E2E scenario/report validation harness
• foundational architecture, parity, performance, and security docs
• CI workflow for formatting, Clippy, tests, indexed-resume performance evidence, and human-emulated terminal-app gates

Quick Start

cargo run -- doctor
cargo run -- metrics
cargo run -- parity
cargo run -- policy shell --json -- git push
cargo run -- config inventory
cargo run -- config features
cargo run -- features list
cargo run -- features enable unified_exec
cargo run -- completion zsh
cargo run -- mcp list
cargo run -- mcp list --json
cargo run -- mcp get github
cargo run -- mcp add docs --url https://example.test/mcp
cargo run -- mcp add github --env GITHUB_TOKEN=token -- npx -y @modelcontextprotocol/server-github
cargo run -- mcp remove github
cargo run -- plugin inventory
cargo run -- plugin inventory --json
cargo run -- app-server --listen stdio://
cargo run -- app-server generate-json-schema --out target/app-server-schema
cargo run -- reference commands
cargo run -- reference capture --out target/reference/codex-local
cargo run -- session summarize ~/.codex/sessions/path/to/session.jsonl
cargo run -- event-log summarize path/to/events.jsonl
cargo run -- event-log index path/to/events.jsonl --out path/to/events.index.json
cargo run -- event-log replay-state path/to/events.jsonl
cargo run -- native-session create --root target/native-sessions --session-id demo
cargo run -- native-session resume-plan --root target/native-sessions --session-id demo
cargo run -- native-session resume-replay --root target/native-sessions --session-id demo
cargo run -- native-session fork --root target/native-sessions --source-session-id demo --target-session-id demo-branch
cargo run -- native-session compact-replay-seed --root target/native-sessions --session-id demo --artifact-id compact-001
cargo run -- native-session compact-summary --root target/native-sessions --session-id demo --artifact-id summary-001 --summary-file summary.md
cargo run -- native-session compact-summary --root target/native-sessions --session-id demo --artifact-id summary-generated-001 --source-file transcript.md --api-key-file ~/.config/openai/api-key
cargo run -- native-session compact-summary --root target/native-sessions --session-id demo --artifact-id summary-auto-001 --from-session --api-key-file ~/.config/openai/api-key
cargo run -- native-session prune-compactions --root target/native-sessions --session-id demo --keep-latest-per-kind 3 --json
cargo run -- native-session prune-compactions --root target/native-sessions --session-id demo --keep-latest-per-kind 3 --apply --json
cargo run -- fixture event-log target/fixtures/smoke.jsonl --events 1000
cargo run -- event-log benchmark target/fixtures/smoke.jsonl
cargo run -- model stream-summary path/to/responses-stream.sse
cargo run -- model stream-to-event-log path/to/responses-stream.sse --event-log target/model-stream.jsonl --session-id demo
cargo run -- model run-turn --native-session-id demo --prompt-file prompt.txt --api-key-file ~/.config/openai/api-key --json
cargo run -- model run-tool-turn --native-session-id demo --prompt-file prompt.txt --api-key-file ~/.config/openai/api-key --approved --json
cargo run -- model run-tool-turn --native-session-id demo --prompt-file prompt.txt --api-key-file ~/.config/openai/api-key --approved --continue-after-tools --json
cargo run -- model run-tool-turn --native-session-id demo --prompt-file prompt.txt --api-key-file ~/.config/openai/api-key --approved --max-tool-rounds 4 --json
cargo run -- tool shell --json --approved -- /bin/sh -c 'printf hello'
cargo run -- tool shell --approved --native-session-root target/native-sessions --native-session-id demo -- /bin/sh -c 'printf hello'
cargo run -- tool pty --json --approved -- /bin/sh -c 'printf hello'
cargo run -- tool pty-live-smoke --json --approved --step input-line:stdin:hello --step drain:500 -- /bin/sh -c 'read line; printf "got:%s\n" "$line"'
cargo run -- view snapshot active-tool-run --cols 96 --rows 24
cargo run -- view resize-flow active-tool-run --json
cargo run -- terminal-app smoke --json --step line:run --step resize:100x20 --step render:stable
cargo run -- terminal-app run --exit-after-submit --max-duration-ms 1500 --json
cargo run -- terminal-app run --native-session-id demo --api-key-file ~/.config/openai/api-key --approved --max-tool-rounds 4 --json
cargo run -- terminal-app run --resume-last --api-key-file ~/.config/openai/api-key --approved --max-tool-rounds 4 --json
cargo run -- terminal-app run --fork-last --fork-target-session-id demo-branch --api-key-file ~/.config/openai/api-key --approved --max-tool-rounds 4 --json
cargo run -- resume --last "status" --sandbox read-only --api-key-file ~/.config/openai/api-key --approved --max-tool-rounds 4 --json
cargo run -- resume --all --json
cargo run -- fork --last "try this branch" --add-dir /tmp/extra-work --target-session-id demo-branch --api-key-file ~/.config/openai/api-key --approved --max-tool-rounds 4 --json
cargo run -- fork --all --json
printf 'extra input' | cargo run -- exec "status" --api-key-file ~/.config/openai/api-key --approved --json --output-last-message target/exec-last-message.txt
printf 'status' | cargo run -- exec resume --last - --api-key-file ~/.config/openai/api-key --approved --json --output-last-message target/last-message.txt
cargo run -- review --uncommitted --api-key-file ~/.config/openai/api-key
printf 'focus tests' | cargo run -- exec review --commit HEAD - --api-key-file ~/.config/openai/api-key --json --output-last-message target/review.txt
cargo run -- apply local-task --patch-file target/change.patch --cwd . --json

Quality gate:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Project Shape

• src/main.rs - CLI entry point
• src/approval.rs - shell risk classification and approval decisions
• src/bench.rs - repeatable local benchmark reports
• src/command_palette.rs - typed terminal command palette model
• src/composer.rs - UTF-8-safe terminal composer controller
• src/doctor.rs - local runtime/environment checks
• src/config.rs - safe config and feature-list inventory parsing
• src/event_index.rs - sparse native event-log index generation
• src/event_log.rs - append-only native event envelope and summary scanner
• src/event_replay.rs - native event-log replay state reducer
• src/fixtures.rs - deterministic event-log fixture generation
• src/human_e2e.rs - human-emulated E2E scenario/report validation
• src/metrics.rs - Codex runtime log metrics parser
• src/mcp.rs - safe MCP server config projection, mutation, and redaction
• src/model.rs - typed Responses API request construction
• src/model_orchestrator.rs - model turn to scheduler orchestration boundary
• src/model_runtime.rs - persisted Responses/native-session turn and continuation runtime
• src/model_stream.rs - Responses API SSE parsing and event-log projection
• src/model_tools.rs - in-memory model function-call to tool-request planning
• src/model_transport.rs - Responses API HTTP transport boundary
• src/parity.rs - initial observable parity matrix
• src/plugin.rs - safe plugin manifest inventory
• src/pty_actor.rs - bounded actor wrapper for live PTY sessions
• src/pty_exec.rs - PTY execution and live controller foundation
• src/pty_runtime.rs - persisted live PTY actor/native-session bridge
• src/pty_script.rs - deterministic scripted live PTY smoke runner
• src/reference.rs - safe local Codex reference capture
• src/render.rs - headless terminal grid, paint, and diff primitives
• src/render_commit.rs - deterministic ANSI commit byte planning
• src/render_loop.rs - pure terminal frame loop and full/diff planner
• src/render_snapshot.rs - stable terminal-frame snapshot serializer
• src/session_replay.rs - streaming JSONL replay metrics
• src/session_resume.rs - native resume-plan construction
• src/session_store.rs - native session-store management
• src/terminal_app.rs - pure terminal app shell and frame wiring
• src/terminal_app_harness.rs - deterministic terminal app E2E harness
• src/terminal_driver.rs - live terminal app raw-mode driver foundation
• src/terminal_input.rs - pure terminal key and paste decoder
• src/terminal_writer.rs - TUI stdout-owner boundary and write metrics
• src/tool_exec.rs - bounded shell execution and tool event projection
• src/tool_runtime.rs - native tool scheduler foundation and active-tool view projection
• src/tools.rs - typed shell tool request/event model
• src/view_fixtures.rs - named terminal view fixtures
• src/views.rs - headless terminal workstation view painters
• docs/PROJECT_PLAN.md - build plan and milestones
• docs/APPROVAL_POLICY.md - shell command approval/risk policy
• docs/ARCHITECTURE.md - native runtime architecture
• docs/COMPOSER.md - terminal composer editing contract
• docs/CONFIG_AND_FEATURES.md - config/feature inventory scope
• docs/EVENT_INDEX.md - sparse event-log index shape and CLI usage
• docs/EVENT_LOG.md - native event log envelope and replay rules
• docs/EVENT_REPLAY.md - native event-log replay report shape
• docs/FIXTURES.md - offline deterministic event-log fixtures
• docs/HUMAN_E2E_HARNESS.md - deterministic E2E scenario/report contract
• docs/HUMAN_E2E_PARITY.md - UI, animation, and performance E2E bar
• docs/MODEL_RUNTIME.md - Responses API runtime direction
• docs/PARITY_MATRIX.md - parity scope and acceptance criteria
• docs/PERFORMANCE_STRATEGY.md - metrics and stress-test posture
• docs/PTY_EXECUTION.md - PTY execution foundation behavior and limits
• docs/REFERENCE_CAPTURE.md - reference capture command scope
• docs/RENDER_COMMIT.md - ANSI byte planning and stdout boundary
• docs/RENDER_LOOP.md - pure frame-loop planning boundary
• docs/RENDER_SNAPSHOTS.md - headless render snapshot format and diffing
• docs/SESSION_REPLAY.md - session replay privacy and large-line behavior
• docs/SESSION_RESUME.md - native resume-plan behavior
• docs/SESSION_STORE.md - native session-store layout and CLI usage
• docs/SECURITY_AND_BOUNDARIES.md - clean-room, auth, and safety limits
• docs/SHELL_EXECUTION.md - bounded shell execution behavior
• docs/TERMINAL_APP.md - pure terminal app shell contract
• docs/TERMINAL_APP_HARNESS.md - scripted terminal app E2E harness
• docs/TERMINAL_DRIVER.md - live terminal driver contract
• docs/TERMINAL_INPUT.md - terminal input decoder contract
• docs/TERMINAL_RENDERER.md - renderer stdout ownership and snapshot plan
• docs/TERMINAL_WRITER.md - TUI writer lifecycle and metrics
• docs/TERMINAL_VIEWS.md - headless terminal view contract
• docs/TOOLS.md - tool event model and privacy boundaries
• docs/VIEW_FIXTURES.md - named terminal view fixtures

Development Standard

Every feature must have an observable compatibility target, typed internal boundary, and verification artifact. Performance claims need benchmark, trace, or replay evidence.