Skip to content

feat(tui): add configurable diff backgrounds#1

Open
ignatremizov wants to merge 3 commits intomainfrom
feat/tui-diff-background-config-upstream
Open

feat(tui): add configurable diff backgrounds#1
ignatremizov wants to merge 3 commits intomainfrom
feat/tui-diff-background-config-upstream

Conversation

@ignatremizov
Copy link
Owner

@ignatremizov ignatremizov commented Feb 26, 2026

Summary

  • add configurable diff background rendering in the TUI via tui.diff_background with modes: auto, off, theme, and custom
  • add unified custom color overrides tui.diff_add_bg / tui.diff_del_bg (single pair, no dark/light split)
  • derive theme mode backgrounds from syntax scopes (markup.inserted/markup.deleted with diff.* fallback), and wire settings at TUI startup
  • update docs and config schema

Validation

  • cd codex-rs && just write-config-schema
  • cd codex-rs && just fmt
  • cd codex-rs && cargo test -p codex-core
  • cd codex-rs && cargo test -p codex-tui

Related issues: openai#12749 openai#12904 openai#12912

Examples:

[tui]
diff_background = "custom"
diff_add_bg = "#213A2B"
diff_del_bg = "#4A221D"
Screenshot 2026-02-26 at 20 34 13
[tui]
diff_background = "off"
Screenshot 2026-02-26 at 20 36 11 Screenshot 2026-02-26 at 20 36 29 Screenshot 2026-02-26 at 20 38 48
[tui]
diff_background = "theme"
  • add .tmTheme files to ~/codex/themes/
Screenshot 2026-02-26 at 20 43 03 Screenshot 2026-02-26 at 20 43 43 Screenshot 2026-02-26 at 20 43 49 Screenshot 2026-02-26 at 20 43 54

…e keys

Add configurable TUI diff line backgrounds so users can keep syntax-theme-aware highlighting while controlling add/delete background intensity, and simplify custom overrides to one add/delete pair because there is no separate runtime dark/light override switch.

Changes:
- Add `tui.diff_background` mode in config (`auto`, `off`, `theme`, `custom`) with schema/docs coverage.
- Add unified custom override keys `tui.diff_add_bg` and `tui.diff_del_bg` (`#RRGGBB`) and remove dark/light-split custom key usage.
- Plumb new config fields from `ConfigToml` into runtime `Config` (`tui_diff_background`, `tui_diff_add_bg`, `tui_diff_del_bg`).
- Add config deserialization/default tests for the new TUI fields.
- Add theme-scope background lookup support in highlight rendering (`markup.inserted`/`markup.deleted` with `diff.*` fallback).
- Add diff renderer background resolution by mode: keep existing adaptive defaults (`auto`), disable line background (`off`), derive from active theme scopes (`theme`), or use user colors with palette-aware quantization (`custom`).
- Initialize diff renderer settings at TUI startup from loaded config.
- Update `docs/config.md` with mode explanations and example custom values.
- Regenerate `core/config.schema.json`.

Behavioral effect:
- Users can reduce bright add/delete backgrounds without replacing the entire theme by setting custom diff backgrounds, disable diff backgrounds entirely, or inherit add/delete backgrounds from their active `.tmTheme` scopes.

Tests:
- `cd codex-rs && just write-config-schema`
- `cd codex-rs && just fmt`
- `cd codex-rs && cargo test -p codex-core`
- `cd codex-rs && cargo test -p codex-tui`
@gemini-code-assist
Copy link

Summary of Changes

Hello @ignatremizov, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Terminal User Interface (TUI) by introducing highly customizable diff background rendering, allowing users to tailor their visual experience for code changes. Beyond visual improvements, it refines agent memory management with new configuration options for memory retention and improves sub-agent spawning by enabling history forking, ensuring better context transfer. Additionally, the changes include more detailed logging for internal tool calls and improved markdown rendering for file links, contributing to a more robust and user-friendly development environment.

Highlights

  • Configurable TUI Diff Backgrounds: Added configurable diff background rendering in the TUI, supporting 'auto', 'off', 'theme', and 'custom' modes. This includes unified custom color overrides (tui.diff_add_bg, tui.diff_del_bg) and the ability to derive theme mode backgrounds from syntax scopes.
  • Enhanced Agent Memory Management: Improved memory consolidation (Phase 2) to track added and removed inputs, updating the consolidation prompt with a diff snapshot. Introduced a max_unused_days configuration for memory retention.
  • Sub-Agent History Forking: Implemented agent history forking for spawned sub-agents, allowing them to inherit the parent's conversation context. This is controlled via a new fork_context argument in the spawn_agent tool.
  • Optional Reasoning Summary Configuration: Refactored model_reasoning_summary to be optional across the codebase, enabling fallback to model catalog defaults when not explicitly set.
  • Improved JS REPL Tool Call Logging: Introduced detailed logging for nested js_repl tool calls, including a new JsReplToolCallResponseSummary struct and functions for summarizing various response types at info and trace levels.
  • Markdown Link Rendering Improvements: Updated markdown rendering for file links to normalize and append line/column suffixes (e.g., :74:3) when not already present in the link label, improving readability.
Changelog
  • codex-rs/Cargo.lock
    • Updated project dependencies.
  • codex-rs/Cargo.toml
    • Reordered and added syntect as a dependency.
  • codex-rs/app-server/tests/common/models_cache.rs
    • Imported ReasoningSummary and initialized default_reasoning_summary in ModelInfo for testing.
  • codex-rs/codex-api/tests/models_integration.rs
    • Imported ReasoningSummary and initialized default_reasoning_summary in ModelInfo for integration tests.
  • codex-rs/core/config.schema.json
    • Added DiffBackgroundMode enum to schema.
    • Introduced max_unused_days for memory configuration.
    • Added tui.diff_background, tui.diff_add_bg, and tui.diff_del_bg to TUI configuration schema.
  • codex-rs/core/src/agent/agent_names.txt
    • Updated agent nicknames from botanical names to historical figures.
  • codex-rs/core/src/agent/control.rs
    • Implemented SpawnAgentOptions for agent spawning.
    • Added spawn_agent_with_options to allow forking parent thread history.
    • Introduced logic to flush parent rollout before forking history.
  • codex-rs/core/src/agent/role.rs
    • Updated the description and rules for the awaiter agent.
  • codex-rs/core/src/codex.rs
    • Made model_reasoning_summary optional in SessionConfiguration.
    • Updated Session::new_turn_context to use default_reasoning_summary if model_reasoning_summary is None.
  • codex-rs/core/src/config/mod.rs
    • Imported DiffBackgroundMode.
    • Added tui_diff_background, tui_diff_add_bg, tui_diff_del_bg to Config struct.
    • Changed model_reasoning_summary to Option<ReasoningSummary>.
    • Added max_unused_days to MemoriesConfig.
  • codex-rs/core/src/config/types.rs
    • Defined DEFAULT_MEMORIES_MAX_UNUSED_DAYS.
    • Added max_unused_days to MemoriesToml and MemoriesConfig.
    • Introduced DiffBackgroundMode enum for TUI diff backgrounds.
  • codex-rs/core/src/memories/README.md
    • Updated Phase 2 memory consolidation description to include max_unused_days and selection diff behavior.
  • codex-rs/core/src/memories/phase2.rs
    • Updated run function to use Phase2InputSelection for memory querying.
    • Adjusted sync_rollout_summaries_from_memories and rebuild_raw_memories_file_from_memories to use artifact_memories_for_phase2.
    • Modified job::succeed to accept selected_outputs.
    • Updated agent::get_prompt to take Phase2InputSelection.
  • codex-rs/core/src/memories/prompts.rs
    • Modified build_consolidation_prompt to include phase2_input_selection.
    • Added render_phase2_input_selection, render_selected_input_line, and render_removed_input_line functions.
  • codex-rs/core/src/memories/storage.rs
    • Added rollout_path to raw_memories.md and rollout summary file generation.
  • codex-rs/core/src/memories/tests.rs
    • Updated sync_rollout_summaries_and_raw_memories_file_keeps_latest_memories_only test to include rollout_path.
    • Updated sync_rollout_summaries_uses_timestamp_hash_and_sanitized_slug_filename test to include rollout_path.
  • codex-rs/core/src/models_manager/model_info.rs
    • Added default_reasoning_summary to ModelInfo.
  • codex-rs/core/src/rollout/recorder.rs
    • Made select_resume_path and select_resume_path_from_db_page async.
    • Introduced resume_candidate_matches_cwd to improve CWD matching logic.
  • codex-rs/core/src/thread_manager.rs
    • Added fork_thread_with_source for agent history forking.
  • codex-rs/core/src/tools/handlers/multi_agents.rs
    • Added fork_context argument to spawn_agent tool.
    • Updated spawn_agent tool to use spawn_agent_with_options.
  • codex-rs/core/src/tools/js_repl/mod.rs
    • Added log_tool_call_response for detailed logging of nested tool calls.
    • Introduced JsReplToolCallResponseSummary and related summarization functions.
    • Updated run_tool_request to use new logging and summarization.
  • codex-rs/core/src/tools/spec.rs
    • Added fork_context boolean argument to spawn_agent tool specification.
  • codex-rs/core/templates/memories/consolidation.md
    • Updated consolidation.md template to include rollout_path.
    • Added phase2_input_selection to the consolidation prompt template.
  • codex-rs/core/templates/memories/read_path.md
    • Updated read_path.md template to include rollout_path details and search instructions.
  • codex-rs/core/tests/responses_headers.rs
    • Updated responses_stream_includes_subagent_header_on_review and responses_stream_includes_subagent_header_on_other tests to use default_reasoning_summary fallback.
  • codex-rs/core/tests/suite/client.rs
    • Updated user_turn_collaboration_mode_overrides_model_and_effort to handle optional model_reasoning_summary.
    • Added reasoning_summary_none_overrides_model_catalog_default test.
  • codex-rs/core/tests/suite/collaboration_instructions.rs
    • Updated collaboration_instructions_added_on_user_turn and user_turn_overrides_collaboration_instructions_after_override tests for optional model_reasoning_summary.
  • codex-rs/core/tests/suite/memories.rs
    • Added new test suite for memory consolidation (memories.rs).
    • Implemented memories_startup_phase2_tracks_added_and_removed_inputs_across_runs test.
  • codex-rs/core/tests/suite/mod.rs
    • Added memories module to the test suite.
  • codex-rs/core/tests/suite/model_switching.rs
    • Updated model_change_from_image_to_text_strips_prior_image_content and model_switch_to_smaller_model_updates_token_context_window tests.
  • codex-rs/core/tests/suite/models_cache_ttl.rs
    • Updated test_remote_model to include default_reasoning_summary.
  • codex-rs/core/tests/suite/personality.rs
    • Updated remote_model_friendly_personality_instructions_with_feature and user_turn_personality_remote_model_template_includes_update_message tests.
  • codex-rs/core/tests/suite/prompt_caching.rs
    • Updated prompt caching tests to use default_reasoning_summary fallback.
  • codex-rs/core/tests/suite/remote_models.rs
    • Updated remote model tests to use default_reasoning_summary fallback and include it in ModelInfo.
  • codex-rs/core/tests/suite/resume_warning.rs
    • Updated resume_history function in resume warning tests to use default_reasoning_summary fallback.
  • codex-rs/core/tests/suite/rmcp_client.rs
    • Updated stdio_image_responses_are_sanitized_for_text_only_model test.
  • codex-rs/core/tests/suite/subagent_notifications.rs
    • Added FORKED_SPAWN_AGENT_OUTPUT_MESSAGE and TURN_0_FORK_PROMPT constants.
    • Implemented spawned_child_receives_forked_parent_context test.
  • codex-rs/core/tests/suite/view_image.rs
    • Updated view_image_tool_returns_unsupported_message_for_text_only_model test.
  • codex-rs/exec/src/lib.rs
    • Updated run_main to use default_reasoning_summary fallback for model_reasoning_summary.
  • codex-rs/protocol/src/openai_models.rs
    • Imported ReasoningSummary.
    • Added default_reasoning_summary to ModelInfo struct.
  • codex-rs/protocol/src/protocol.rs
    • Changed memory consolidation subagent nickname to 'Morpheus'.
  • codex-rs/state/migrations/0018_phase2_selection_snapshot.sql
    • Added 0018_phase2_selection_snapshot.sql migration file.
    • Added selected_for_phase2_source_updated_at column to stage1_outputs table.
    • Added memory_mode column to threads table.
  • codex-rs/state/src/extract.rs
    • Modified apply_turn_context to prevent overwriting an existing cwd.
  • codex-rs/state/src/lib.rs
    • Exported Phase2InputSelection and Stage1OutputRef.
  • codex-rs/state/src/model/memories.rs
    • Added rollout_path field to Stage1Output.
    • Introduced Stage1OutputRef struct.
    • Defined Phase2InputSelection struct for memory selection.
  • codex-rs/state/src/model/mod.rs
    • Exported Phase2InputSelection and Stage1OutputRef from model module.
  • codex-rs/state/src/runtime/agent_jobs.rs
    • Added new file agent_jobs.rs for agent job management.
    • Implemented create_agent_job, get_agent_job, list_agent_job_items, mark_agent_job_running, mark_agent_job_completed, mark_agent_job_failed, mark_agent_job_cancelled, is_agent_job_cancelled, mark_agent_job_item_running, mark_agent_job_item_running_with_thread, mark_agent_job_item_pending, set_agent_job_item_thread, report_agent_job_item_result, mark_agent_job_item_completed, mark_agent_job_item_failed, and get_agent_job_progress.
  • codex-rs/state/src/runtime/backfill.rs
    • Added new file backfill.rs for backfill state management.
    • Implemented get_backfill_state, try_claim_backfill, mark_backfill_running, checkpoint_backfill, and mark_backfill_complete.
  • codex-rs/state/src/runtime/logs.rs
    • Added new file logs.rs for log management.
    • Implemented insert_log, insert_logs, prune_logs_after_insert, delete_logs_before, query_logs, and max_log_id.
  • codex-rs/state/src/runtime/test_support.rs
    • Added new file test_support.rs with test utility functions.
  • codex-rs/state/src/runtime/threads.rs
    • Added new file threads.rs for thread management.
    • Implemented get_thread, get_dynamic_tools, find_rollout_path_by_id, list_threads, list_thread_ids, upsert_thread, persist_dynamic_tools, apply_rollout_items, mark_archived, mark_unarchived, and delete_thread.
  • codex-rs/tui/Cargo.toml
    • Added codex-utils-string dependency.
  • codex-rs/tui/src/app.rs
    • Refactored application exit logic into a new handle_exit_mode function.
  • codex-rs/tui/src/chatwidget.rs
    • Updated new_turn_context to use default_reasoning_summary fallback for model_reasoning_summary.
  • codex-rs/tui/src/diff_render.rs
    • Introduced DiffBackgroundSettings struct.
    • Added set_diff_background_settings and current_diff_background_settings.
    • Implemented resolve_line_backgrounds for dynamic diff background styling.
    • Added parse_hex_rgb, resolve_theme_scope_rgb, and quantize_rgb helper functions.
  • codex-rs/tui/src/lib.rs
    • Called set_diff_background_settings during TUI startup.
    • Updated new_turn_context to use default_reasoning_summary fallback for model_reasoning_summary.
  • codex-rs/tui/src/markdown_render.rs
    • Added COLON_LOCATION_SUFFIX_RE and HASH_LOCATION_SUFFIX_RE for parsing location suffixes.
    • Modified pop_link to normalize and append location suffixes to file links.
  • codex-rs/tui/src/markdown_render_tests.rs
    • Added tests for file_link_appends_line_number_when_label_lacks_it and file_link_uses_label_for_line_number.
    • Added tests for hash anchors and ranges in file links.
  • codex-rs/tui/src/render/highlight.rs
    • Added scope_background_rgb function to retrieve theme background colors.
  • codex-rs/tui/src/snapshots/codex_tui__markdown_render__markdown_render_tests__markdown_render_file_link_snapshot.snap
    • Updated markdown_render_file_link_snapshot.snap.
  • codex-rs/tui/src/status/card.rs
    • Updated StatusHistoryCell to handle optional model_reasoning_summary display.
  • codex-rs/tui/src/status/tests.rs
    • Updated status snapshot tests for optional model_reasoning_summary.
  • codex-rs/utils/sandbox-summary/src/config_summary.rs
    • Updated create_config_summary_entries to handle optional model_reasoning_summary display.
  • codex-rs/utils/string/src/lib.rs
    • Added normalize_markdown_hash_location_suffix and parse_markdown_hash_location_point functions.
  • docs/config.md
    • Updated documentation to include new TUI diff background configuration options.
  • docs/js_repl.md
    • Updated documentation to include debug logging instructions for nested js_repl tool calls.
Activity
  • The pull request was opened by ignatremizov.
  • Initial review requested.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new feature for configurable diff backgrounds in the TUI. It adds new configuration options tui.diff_background, tui.diff_add_bg, and tui.diff_del_bg to control the appearance of diffs. The implementation involves changes to the configuration schema, core config structs, and the TUI rendering logic. The documentation has also been updated accordingly.

My review focuses on the implementation details. I've suggested a couple of refactorings to improve code clarity and reduce duplication in the rendering logic. Overall, the changes are well-implemented and the new feature is a great addition.

Combine the DiffBackgroundMode::Theme and DiffBackgroundMode::Custom branches in resolve_line_backgrounds by selecting RGB sources once and sharing the same quantize/fallback path. This reduces duplication while preserving behavior for off/auto/theme/custom modes.
…okup

Acquire the read guard once in scope_background_rgb and reuse it for style lookup. Preserve poisoned lock recovery while removing duplicated lock-branch highlighter logic.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant