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