docs: updated documentation for describing tips and design decisions#1
docs: updated documentation for describing tips and design decisions#1prravda wants to merge 3 commits intoOutlineDriven:mainfrom
Conversation
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
There was a problem hiding this comment.
Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughREADME.md rewritten: formatting changes, "Clean Install" renamed to "TL;DR" with a new subheading, sections reorganized, and expanded "Tips" and "Design decisions and codex’s configurations" content added (including Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Updated links in README to use relative paths instead of url
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 84-96: In the README's agents section (the "### [agents]" block)
fix the broken Notion link by replacing the private workspace URL with either a
public documentation link or remove the link; correct typos and grammar in the
explanatory text by changing "baed" to "based", "pro subscription" to "a ChatGPT
Pro subscription" (or "a Pro subscriber" in the conditional), and "buf" to
"but"; ensure the sample model lines (e.g., model = "gpt-5.3-codex-spark" and
model = "gpt-5.1-codex-mini") remain unchanged except for clarifying comments if
needed for non-Pro users.
- Around line 29-49: Update the Tips text for correct grammar and
capitalization: change the heading "Keep upgrade codex up-to-date" to a clearer
title like "Keep Codex up-to-date" or "Upgrade Codex regularly"; in the sentence
about installs replace "Due to codex’s features are upgraded in silent and
sometimes they’re significantly effective, upgrade codex(-cli) on your host
machine consistently." with a grammatically correct version using "because" and
"silently" and capitalize "Codex" and "Codex(-cli)"; change "Set plan mode" note
to use "in Codex" instead of "on codex"; in the Steering block replace "it
trigger" with "it triggers"; change "Don't need to interrupt by triggering `esc`
or wait the plan is fully done. Sometime you feel codex ask you for gathering
more context to make better plan." to "You don't need to interrupt with `Esc` or
wait for the plan to finish. Sometimes Codex asks you for more context to make a
better plan." and ensure consistent capitalization for "Codex" and punctuation.
- Around line 52-72: Fix the README configuration section by correcting grammar
and the broken/private link: reword the opening sentence to "Basically, this
project has enabled efficient Codex features, some of which are experimental but
battle-tested, in .codex/config.toml."; remove or replace the private Notion
link under the [config.toml] heading with a local or public reference (e.g.,
just "config.toml" or a public docs URL); change "project_doc_fallback_filenames
are fallback constitution files" to "project_doc_fallback_filenames is a list of
fallback constitution filenames (list[str])"; replace "feel these props which
you’re using before" with "feel free to add other constitutions you've used
before"; change "due to save token" to "to save tokens"; keep keys like
model_reasoning_effort, model_verbosity, project_doc_fallback_filenames,
personality, compaction_prompt, and memories intact.
| ### Keep upgrade codex up-to-date | ||
|
|
||
| ```bash | ||
| npm i -g @openai/codex@latest | ||
| ``` | ||
|
|
||
| - Due to codex’s features are upgraded in silent and sometimes they’re significantly effective, upgrade codex(-cli) on your host machine consistently. | ||
|
|
||
| ### Set plan mode | ||
|
|
||
| - You can turn on plan mode on codex by `shift + tab` shortcut. | ||
|
|
||
| ### Steering | ||
|
|
||
| ```bash | ||
| # it trigger `/prompts:askme` prompt, which is designed for gathering more context during planning | ||
| askme | ||
| ``` | ||
|
|
||
| - Don't need to interrupt by triggering `esc` or wait the plan is fully done. Sometime you feel codex ask you for gathering more context to make better plan. | ||
|
|
There was a problem hiding this comment.
Fix grammatical errors in the Tips section.
Multiple grammatical and typographical errors affect readability:
- Line 29: "Keep upgrade codex" should be "Keep Codex up-to-date" or "Upgrade Codex regularly"
- Line 35: "upgraded in silent" should be "upgraded silently"; "due to" should be "because"
- Line 39: Missing article - "on codex" should be "in Codex"
- Line 44: "it trigger" should be "it triggers"
- Line 48: Missing subject - "Don't need" should be "You don't need"; "Sometime" should be "Sometimes"; "codex ask you" should be "Codex is asking you" or "Codex asks you"
📝 Proposed fixes for grammar issues
-### Keep upgrade codex up-to-date
+### Keep Codex up-to-date
-- Due to codex's features are upgraded in silent and sometimes they're significantly effective, upgrade codex(-cli) on your host machine consistently.
+- Because Codex features are upgraded silently and sometimes they're significantly effective, upgrade Codex (CLI) on your host machine consistently.
-- You can turn on plan mode on codex by `shift + tab` shortcut.
+- You can turn on plan mode in Codex using the `Shift + Tab` shortcut.
- # it trigger `/prompts:askme` prompt, which is designed for gathering more context during planning
+ # it triggers the `/prompts:askme` prompt, which is designed for gathering more context during planning
-- Don't need to interrupt by triggering `esc` or wait the plan is fully done. Sometime you feel codex ask you for gathering more context to make better plan.
+- You don't need to interrupt by pressing `Esc` or wait for the plan to be fully done. Sometimes you might feel Codex is asking you to gather more context to make a better plan.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Keep upgrade codex up-to-date | |
| ```bash | |
| npm i -g @openai/codex@latest | |
| ``` | |
| - Due to codex’s features are upgraded in silent and sometimes they’re significantly effective, upgrade codex(-cli) on your host machine consistently. | |
| ### Set plan mode | |
| - You can turn on plan mode on codex by `shift + tab` shortcut. | |
| ### Steering | |
| ```bash | |
| # it trigger `/prompts:askme` prompt, which is designed for gathering more context during planning | |
| askme | |
| ``` | |
| - Don't need to interrupt by triggering `esc` or wait the plan is fully done. Sometime you feel codex ask you for gathering more context to make better plan. | |
| ### Keep Codex up-to-date | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 29 - 49, Update the Tips text for correct grammar and
capitalization: change the heading "Keep upgrade codex up-to-date" to a clearer
title like "Keep Codex up-to-date" or "Upgrade Codex regularly"; in the sentence
about installs replace "Due to codex’s features are upgraded in silent and
sometimes they’re significantly effective, upgrade codex(-cli) on your host
machine consistently." with a grammatically correct version using "because" and
"silently" and capitalize "Codex" and "Codex(-cli)"; change "Set plan mode" note
to use "in Codex" instead of "on codex"; in the Steering block replace "it
trigger" with "it triggers"; change "Don't need to interrupt by triggering `esc`
or wait the plan is fully done. Sometime you feel codex ask you for gathering
more context to make better plan." to "You don't need to interrupt with `Esc` or
wait for the plan to finish. Sometimes Codex asks you for more context to make a
better plan." and ensure consistent capitalization for "Codex" and punctuation.
| > Basically, this project already turned on efficient features of codex, somethings are experimental state but battle-tasted, in .codex/config.toml. This section is going to tell about the decisions. | ||
| > | ||
|
|
||
| ### [config.toml](https://www.notion.so/prravda/config.toml) | ||
|
|
||
| ```toml | ||
| model_reasoning_effort = "high" | ||
| model_verbosity = "high" | ||
| approval_policy = "on-request" | ||
| sandbox_mode = "workspace-write" | ||
| project_doc_fallback_filenames = ["CLAUDE.md"] | ||
| model = "gpt-5.4" | ||
| personality = "pragmatic" | ||
| ``` | ||
|
|
||
| - `model_reasoning_effort`, and `model_verbosity` set high as default due to high performance. | ||
| - `project_doc_fallback_filenames` are fallback constitution files. The type of this property is `list[str]`, so you can add `str` type element into this section like `["CLAUDE.md", "AGENTS.md", "CRUSH.md"]`. | ||
| - If you want to reuse other constitutions, feel these props which you’re using before. | ||
| - set `personality` as `pragmatic` due to save token(direct communication) | ||
| - polished `compaction_prompt` for better context compaction. | ||
| - `memories`: codex also supports detecting and saving user’s tastes. |
There was a problem hiding this comment.
Fix grammatical errors and broken links in the configuration section.
Multiple issues affect documentation quality:
- Line 52: "somethings" should be "some things" or "some of which"; "experimental state" should be "in an experimental state"; "battle-tasted" should be "battle-tested"
- Line 55: The Notion link appears to be a private/personal workspace URL that won't be accessible to users
- Line 68: Missing article - should be "is a list of fallback constitution files"
- Line 69: Unclear phrasing - "feel these props which you're using before" should be "feel free to add other constitutions you've used before"
- Line 70: "due to save token" should be "to save tokens"
📝 Proposed fixes
-> Basically, this project already turned on efficient features of codex, somethings are experimental state but battle-tasted, in .codex/config.toml. This section is going to tell about the decisions.
+> Basically, this project has already enabled efficient features of Codex, some of which are in an experimental state but battle-tested, in .codex/config.toml. This section describes the decisions behind these configurations.
-### [config.toml](https://www.notion.so/prravda/config.toml)
+### config.toml
-- `project_doc_fallback_filenames` are fallback constitution files. The type of this property is `list[str]`, so you can add `str` type element into this section like `["CLAUDE.md", "AGENTS.md", "CRUSH.md"]`.
- - If you want to reuse other constitutions, feel these props which you're using before.
+- `project_doc_fallback_filenames` is a list of fallback constitution files. The type of this property is `list[str]`, so you can add string elements to this section like `["CLAUDE.md", "AGENTS.md", "CRUSH.md"]`.
+ - If you want to reuse other constitutions, feel free to add ones you've used before.
-- set `personality` as `pragmatic` due to save token(direct communication)
+- set `personality` as `pragmatic` to save tokens (direct communication)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 52 - 72, Fix the README configuration section by
correcting grammar and the broken/private link: reword the opening sentence to
"Basically, this project has enabled efficient Codex features, some of which are
experimental but battle-tested, in .codex/config.toml."; remove or replace the
private Notion link under the [config.toml] heading with a local or public
reference (e.g., just "config.toml" or a public docs URL); change
"project_doc_fallback_filenames are fallback constitution files" to
"project_doc_fallback_filenames is a list of fallback constitution filenames
(list[str])"; replace "feel these props which you’re using before" with "feel
free to add other constitutions you've used before"; change "due to save token"
to "to save tokens"; keep keys like model_reasoning_effort, model_verbosity,
project_doc_fallback_filenames, personality, compaction_prompt, and memories
intact.
Summary of ChangesHello, 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 documentation for the Highlights
Changelog
Activity
Using Gemini Code AssistThe 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
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 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
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The pull request updates the README.md file to include a TL;DR section, tips for keeping Codex up-to-date and setting plan mode, steering instructions, and design decisions related to Codex configurations. Review comments suggest improvements to grammar, clarity, and word choice throughout the added documentation, including correcting typos and suggesting more professional language.
Note: Security Review has been skipped due to the limited scope of the PR.
| askme | ||
| ``` | ||
|
|
||
| - Don't need to interrupt by triggering `esc` or wait the plan is fully done. Sometime you feel codex ask you for gathering more context to make better plan. |
There was a problem hiding this comment.
There's a typo here; "Sometime" should be "Sometimes". Also, the phrasing "you feel codex ask you" is a bit informal. Consider: "Sometimes codex may require more context to formulate a better plan."
| - Don't need to interrupt by triggering `esc` or wait the plan is fully done. Sometime you feel codex ask you for gathering more context to make better plan. | |
| - Don't need to interrupt by triggering `esc` or wait the plan is fully done. Sometimes you feel codex ask you for gathering more context to make better plan. |
|
|
||
| ## Design decisions and codex’s configurations | ||
|
|
||
| > Basically, this project already turned on efficient features of codex, somethings are experimental state but battle-tasted, in .codex/config.toml. This section is going to tell about the decisions. |
There was a problem hiding this comment.
There's a typo; "somethings" should be "some things". Additionally, "battle-tasted" is an uncommon phrase; "battle-tested" is more appropriate.
| > Basically, this project already turned on efficient features of codex, somethings are experimental state but battle-tasted, in .codex/config.toml. This section is going to tell about the decisions. | |
| > Basically, this project already turned on efficient features of codex, some things are experimental state but battle-tested, in .codex/config.toml. This section is going to tell about the decisions. |
|
|
||
| - `model_reasoning_effort`, and `model_verbosity` set high as default due to high performance. | ||
| - `project_doc_fallback_filenames` are fallback constitution files. The type of this property is `list[str]`, so you can add `str` type element into this section like `["CLAUDE.md", "AGENTS.md", "CRUSH.md"]`. | ||
| - If you want to reuse other constitutions, feel these props which you’re using before. |
There was a problem hiding this comment.
This sentence is a bit unclear. Consider rephrasing for better readability, such as: "If you want to reuse other constitutions, feel free to use these properties if you've used them before."
| - If you want to reuse other constitutions, feel these props which you’re using before. | |
| - If you want to reuse other constitutions, feel free to use these props which you’re using before. |
| - `model_reasoning_effort`, and `model_verbosity` set high as default due to high performance. | ||
| - `project_doc_fallback_filenames` are fallback constitution files. The type of this property is `list[str]`, so you can add `str` type element into this section like `["CLAUDE.md", "AGENTS.md", "CRUSH.md"]`. | ||
| - If you want to reuse other constitutions, feel these props which you’re using before. | ||
| - set `personality` as `pragmatic` due to save token(direct communication) |
There was a problem hiding this comment.
The phrase "due to save token" is grammatically incorrect. It should be "to save tokens".
| - set `personality` as `pragmatic` due to save token(direct communication) | |
| - set `personality` as `pragmatic` to save token(direct communication) |
| - If you want to reuse other constitutions, feel these props which you’re using before. | ||
| - set `personality` as `pragmatic` due to save token(direct communication) | ||
| - polished `compaction_prompt` for better context compaction. | ||
| - `memories`: codex also supports detecting and saving user’s tastes. |
There was a problem hiding this comment.
The term "user's tastes" is informal. Consider using more professional language like "user preferences" or "user's interaction patterns."
| - `memories`: codex also supports detecting and saving user’s tastes. | |
| - `memories`: codex also supports detecting and saving user’s preferences. |
| job_max_runtime_seconds = 36000 # Default: 1800 seconds | ||
| ``` | ||
|
|
||
| - codex could call agent(s) in recursively, by following max_depth. |
There was a problem hiding this comment.
This sentence is grammatically awkward. Consider rephrasing it for better flow, for example: "But if your host machine or quota is limited, set these values, including max_depth, appropriately."
| - codex could call agent(s) in recursively, by following max_depth. | |
| - But if your host machine or quota is limited, set these values including max_depth appropriately as you want. |
| model = "gpt-5.3-codex-spark" | ||
| ``` | ||
|
|
||
| - some `fast` agents baed on spark model. But this model is only available on ChatGPT pro subscription. So if you're not pro subscriber, change them into appropriate models. |
There was a problem hiding this comment.
There's a typo here; "baed" should be "based".
| - some `fast` agents baed on spark model. But this model is only available on ChatGPT pro subscription. So if you're not pro subscriber, change them into appropriate models. | |
| - some `fast` agents based on spark model. But this model is only available on ChatGPT pro subscription. So if you're not pro subscriber, change them into appropriate models. |
| - some `fast` agents baed on spark model. But this model is only available on ChatGPT pro subscription. So if you're not pro subscriber, change them into appropriate models. | ||
|
|
||
| ```toml | ||
| model = "gpt-5.1-codex-mini" |
There was a problem hiding this comment.
There's a typo here; "buf" should be "but". Also, the phrasing could be improved for clarity.
| model = "gpt-5.1-codex-mini" | |
| - set `explore` agent use `gpt-5.1-codex-mini`, because they consume little quota but are sufficient for exploration. |
1 participant
described tips(consistent codex update recommended, turn on plan mode), configuration, and design decisions.
Summary by CodeRabbit