Skip to content

docs: updated documentation for describing tips and design decisions #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
prravda wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: updated documentation for describing tips and design decisions #1

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
23c0dc7
docs: updated documentation for describing tips and design decisions
prravda Mar 10, 2026
0820e8a
Change links in README to relative paths
prravda Mar 10, 2026
e3d1f6f
Merge branch 'OutlineDriven:main' into main
prravda Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 78 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
# odin-codex-plugin
ODIN [for Codex CLI as a plugin] - Outline Driven development approach for agentic INtelligence

**ODIN [for Codex CLI as a plugin]** - **O**utline **D**riven development approach for agentic **IN**telligence

## Clean Install (Recommended)
## TL;DR

### Clean Install (Recommended)

```bash
rm -rf ~/.codex/
Expand All @@ -11,11 +13,84 @@ git clone https://github.com/OutlineDriven/odin-codex-plugin ~/.codex

---

## Overwrite Install
### Overwrite Install

```bash
git clone https://github.com/OutlineDriven/odin-codex-plugin
mv ./odin-codex-plugin/* ~/.codex/
```

That easy.

---

## Tips

### 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.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

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."

Suggested 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.
- 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.


Comment on lines +29 to +49
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 10, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
### 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.

## 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.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

There's a typo; "somethings" should be "some things". Additionally, "battle-tasted" is an uncommon phrase; "battle-tested" is more appropriate.

Suggested change
> 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.

>

### [config.toml](./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.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

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."

Suggested change
- 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.

- set `personality` as `pragmatic` due to save token(direct communication)
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

The phrase "due to save token" is grammatically incorrect. It should be "to save tokens".

Suggested change
- set `personality` as `pragmatic` due to save token(direct communication)
- set `personality` as `pragmatic` to save token(direct communication)

- polished `compaction_prompt` for better context compaction.
- `memories`: codex also supports detecting and saving user’s tastes.
Comment on lines +52 to +72
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 10, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

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.

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

The term "user's tastes" is informal. Consider using more professional language like "user preferences" or "user's interaction patterns."

Suggested change
- `memories`: codex also supports detecting and saving user’s tastes.
- `memories`: codex also supports detecting and saving user’s preferences.


```toml
[agents]
max_depth = 2
max_threads = 96
job_max_runtime_seconds = 36000 # Default: 1800 seconds
```

- codex could call agent(s) in recursively, by following max_depth.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

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."

Suggested change
- 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.

- But if host machine or your quota is limited, set these values including max_depth appropriately as you want.

### [agents](./agents/)

```toml
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.
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

There's a typo here; "baed" should be "based".

Suggested change
- 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.


```toml
model = "gpt-5.1-codex-mini"
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Mar 10, 2026

Choose a reason for hiding this comment

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

medium

There's a typo here; "buf" should be "but". Also, the phrasing could be improved for clarity.

Suggested change
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.

```

- set `explore` agent use `gpt-5.1-codex-mini`, because they consume little quota buf sufficient for exploration.