Add portable Codex ops kit

2026-04-12 14:00:55 +01:00
commit aa907983db
19 changed files with 679 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Research Notes
+
+Research date: `2026-04-12`
+
+## Reliable Takeaways
+
+1. OpenAI's `Codex Prompting Guide` says `medium` reasoning effort is the recommended all-around default, while `high` or `xhigh` should be reserved for harder work. It also calls out compaction as a first-class way to support long-running conversations without hitting context limits.
+Source: [Codex Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide)
+
+2. OpenAI's configuration reference supports profile-scoped overrides, including `profiles.<name>.model`, `profiles.<name>.model_reasoning_effort`, `profiles.<name>.model_instructions_file`, `profiles.<name>.web_search`, `project_doc_max_bytes`, and `history.max_bytes`.
+Source: [Configuration Reference](https://developers.openai.com/codex/config-reference)
+
+3. OpenAI's slash-command docs show that `/status` exposes token usage and `/statusline` can persist footer items like model, context, limits, tokens, and session id. That makes it easier to notice expensive sessions before they sprawl.
+Source: [Slash commands in Codex CLI](https://developers.openai.com/codex/cli/slash-commands)
+
+4. The `GPT-5.3-Codex` model page lists a large discount for cached input tokens compared with regular input tokens. This supports a strategy of keeping stable instructions and repeated context in consistent, reusable front-loaded text instead of rewriting them ad hoc every session.
+Source: [GPT-5.3-Codex model page](https://developers.openai.com/api/docs/models/gpt-5.3-codex)
+
+5. An arXiv paper published in 2026 found that adding repository-level `AGENTS.md` files was associated with lower median runtime and reduced output-token usage while keeping comparable task completion behavior.
+Source: [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/abs/2601.20404)
+
+## Community Signals
+
+1. Community writeups consistently recommend small, specific `AGENTS.md` files instead of large prose dumps. The basic pattern is to keep the instruction layer lean and push durable knowledge into separate reusable notes.
+Source: [Codex CLI reference guide](https://blakecrosley.com/guides/codex)
+
+2. There is active experimentation around external or MCP-backed memory systems so that project knowledge survives across restarts and across tools. I treated these as directional input rather than source-of-truth guidance because they are not official OpenAI docs.
+Source: [Memory for Codex discussion](https://www.reddit.com/r/codex/comments/1rmhtmr/memory_for_codex/)
+
+## Design Decisions For This Kit
+
+- Keep the always-loaded instruction surface short.
+- Use profiles instead of one global "best" model choice.
+- Separate durable markdown memory from bulky session history.
+- Default maintenance scripts to audit and dry-run, not deletion.
+- Export only portable assets: config, instructions, memory, and scripts. Do not export auth or giant local databases.