tevansandClaude Opus 4.8
aedbf8a515
Codex 0.144+ refuses to load any config containing the top-level
`profile = "..."` key or `[profiles.<name>]` tables, so every machine running
the kit's output hit "Error loading configuration" and codex would not start.
Profiles now live in per-profile files:
- templates/global/{economy,balanced,deep}.config.toml, installed to
~/.codex/<name>.config.toml and selected with `codex --profile <name>`
- config.toml keeps the balanced values as its defaults, so plain `codex`
behaves as before without a profile selector
`profile` and `profiles.*` stay in the installer's strip lists so upgrading an
existing machine removes the legacy keys from its live config.
Also fixes two latent bugs in the merge, both hit while testing the above:
- Only text *before* the managed block was retained, so anything after it was
silently deleted on every install. `codex mcp add` appends [mcp_servers.*] to
the end of config.toml, so those servers would be wiped. Both sides are now
kept and filtered.
- The config was read with the locale default encoding and a leading BOM was
preserved, which could strand the BOM mid-file once content was merged around
the block -- invalid TOML. Read as utf-8-sig, write utf-8.
Verified against a seeded legacy config (BOM at byte 0, machine-specific
[mcp_servers] on both sides of the block): legacy keys stripped, both sides
preserved, idempotent across three runs, and `codex --profile economy exec`
returns a live model response.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
104 lines
3.5 KiB
Markdown
104 lines
3.5 KiB
Markdown
# Codex Ops Kit
|
|
|
|
This repository turns a local Codex setup into something you can keep lean, remember more usefully, and share across machines without dragging along secrets or multi-gigabyte session logs.
|
|
|
|
## What We Improved
|
|
|
|
- Added explicit Codex profiles for `economy`, `balanced`, and `deep` work.
|
|
- Added a short global `AGENTS.md` pattern that tells Codex where to find durable memory without bloating every session.
|
|
- Added portable memory files you can keep in Git and sync between machines.
|
|
- Added audit, export, install, and session-maintenance scripts.
|
|
- Documented research-backed guidance from current OpenAI docs plus community findings.
|
|
|
|
## Findings From This Machine
|
|
|
|
Audit date: `2026-04-12`
|
|
|
|
- `~/.codex/sessions` was about `2.8G`.
|
|
- `~/.codex/state_5.sqlite` was about `227M`.
|
|
- `~/.codex/memories` was empty.
|
|
- Current config only set the model and plugin flags, so there were no cost-oriented profiles or memory workflow conventions in place.
|
|
|
|
The biggest issue was not a lack of raw stored data. It was that durable, reusable knowledge was not being separated from bulky transcript history.
|
|
|
|
## Repo Layout
|
|
|
|
- `docs/research.md`
|
|
- `docs/new-machine-setup.md`
|
|
- `templates/global/AGENTS.md`
|
|
- `templates/global/config.toml`
|
|
- `memory/`
|
|
- `scripts/`
|
|
|
|
## Local Setup
|
|
|
|
Install this kit into your current Codex home:
|
|
|
|
```bash
|
|
bash scripts/install_codex_kit.sh
|
|
```
|
|
|
|
Set up a fresh machine from this repo:
|
|
|
|
```bash
|
|
git clone https://github.com/slaguru666/codex-ops-kit.git
|
|
cd codex-ops-kit
|
|
bash scripts/install_codex_kit.sh
|
|
```
|
|
|
|
Create a portable export bundle you can move to another machine:
|
|
|
|
```bash
|
|
bash scripts/export_codex_portable.sh
|
|
```
|
|
|
|
Audit your live Codex home:
|
|
|
|
```bash
|
|
bash scripts/audit_codex_home.sh
|
|
```
|
|
|
|
Preview old session files that are taking space:
|
|
|
|
```bash
|
|
bash scripts/prune_codex_sessions.sh
|
|
```
|
|
|
|
Archive old session files after reviewing the plan:
|
|
|
|
```bash
|
|
bash scripts/prune_codex_sessions.sh --apply
|
|
```
|
|
|
|
Extract a markdown summary skeleton from a large session transcript:
|
|
|
|
```bash
|
|
python3 scripts/session_to_memory.py ~/.codex/sessions/2026/03/19/rollout-....jsonl
|
|
```
|
|
|
|
## Recommended Workflow
|
|
|
|
Use `balanced` for normal work, `economy` for quick edits and low-risk tasks, and `deep` only for the hard stuff.
|
|
|
|
Keep `AGENTS.md` concise. Put stable personal preferences, project summaries, and long-lived decisions into the markdown files under `memory/`.
|
|
|
|
When a long session finishes, distill the durable facts into memory notes instead of relying on Codex to rediscover them from old transcript files.
|
|
|
|
Run the audit script periodically. If session storage balloons again, archive the biggest old transcripts instead of letting `~/.codex/sessions` become your accidental memory system.
|
|
|
|
## Profiles
|
|
|
|
- `economy`: lowest-cost default for shallow work
|
|
- `balanced`: everyday profile
|
|
- `deep`: higher-effort work when architecture or debugging really needs it
|
|
|
|
Each profile is defined in its own `templates/global/<name>.config.toml` and is installed to `~/.codex/<name>.config.toml`. Select one with `codex --profile <name>`; plain `codex` uses the `config.toml` defaults, which match `balanced`.
|
|
|
|
Codex 0.144+ rejects the legacy top-level `profile = "..."` key and `[profiles.<name>]` tables, so the kit no longer emits them and strips them from a live config on upgrade.
|
|
|
|
The installer merges the managed cost and memory block into your live `~/.codex/config.toml`, preserving machine-specific settings that appear *before* the managed block.
|
|
|
|
## New Machine Rollout
|
|
|
|
Use the short guide in `docs/new-machine-setup.md` when bringing another Mac or workstation onto the same Codex setup.
|