Codex Coach

Codex Coach is a local-first usage coach for Codex users. It reads Codex session logs on your machine, generates redacted habit reports, and suggests reviewable improvements to your Codex configuration and project instructions.

Quick Start

1. Install it:

npm install -g codex-coach
codex-coach install

2. Restart Codex, then ask in a Codex prompt:

Coach my Codex usage

3. Read the output report:

• Latest report: ~/.codex-coach/reports/latest.md
• Weekly copy: ~/.codex-coach/reports/weekly-YYYY-MM-DD.md
• Example: demo report

Install Options

With npm:

npm install -g codex-coach
codex-coach install

From a checkout:

./install.sh

Windows PowerShell:

.\install.ps1

The installer adds the codex-coach command when possible, copies the Codex plugin/skill into your local Codex plugin directory, and writes a default config under ~/.codex-coach/.

Install options:

./install.sh --weekly       # default weekly report
./install.sh --daily        # opt-in daily scheduled report
./install.sh --no-schedule  # manual-only

.\install.ps1 -Daily
.\install.ps1 -NoSchedule

Use

codex-coach doctor
codex-coach scan --since 7d
codex-coach report --since 7d
codex-coach report --since 7d --mode expert
codex-coach suggest-config
codex-coach instructions scan --since 30d
codex-coach instructions report --since 30d
codex-coach instructions suggest --since 30d
codex-coach lint-prompt "fix the failing auth test and verify pytest passes"

Inside Codex, ask:

Coach my Codex usage
Show my weekly Codex Coach report
Suggest custom instruction changes

Weekly Heartbeat

In the Codex app, paste this prompt to ask Codex to set a weekly check-in:

Set a weekly Codex Coach check-in every 7 days. Use medium intelligence for the routine review. Each week, run `codex-coach report --since 7d`, read `~/.codex-coach/reports/latest.md`, compare it with the previous report, and give me a concise TL;DR with the top 3 changes and exact next actions. Escalate to high only if the report shows security risk, production risk, repeated failures, or major architecture concerns.

CLI, VS Code, Cursor, and Windsurf users can run the same review manually:

codex-coach report --since 7d

Privacy Model

• Local only by default.
• Reads ~/.codex/sessions/**/*.jsonl and ~/.codex/archived_sessions/*.jsonl.
• Reports do not include full prompt text or source code.
• Suggestions are written as review files and are never applied automatically.

Outputs

• ~/.codex-coach/reports/latest.md
• ~/.codex-coach/reports/weekly-YYYY-MM-DD.md
• ~/.codex-coach/facts/latest.json
• ~/.codex-coach/facts/report-latest.json
• ~/.codex-coach/instructions/index.json
• ~/.codex-coach/suggestions/*.patch.md

Coaching Features

• Project capsules: redacted per-project workflow summaries with suggested local instructions.
• Prompt rewrites: safe templates for vague prompts without storing full prompt text.
• Confidence-scored suggestions: low, medium, or high confidence improvement notes.
• TL;DR action plan: skimmable beginner-friendly changes with where to make them, whether they belong in settings, a prompt, or AGENTS.md, and collapsible Markdown snippets.
• Since Last Report: a small Markdown trend panel comparing the current report with the previous report baseline.
• Token efficiency: cached vs uncached input, output, routing, and context-budget recommendations.
• Weekly Check-In: a pasteable Codex app heartbeat prompt with recommended medium intelligence for routine 7-day reviews.
• Beginner and expert report modes.
• Skill opportunities: repeated workflow patterns that may deserve a reusable Codex skill.
• Real-time prompt linting through codex-coach lint-prompt.
• Instruction Playbook Audit: review global custom instructions and project AGENTS.md files for stale mode locks, scope leaks, missing verification rules, secrets, and active projects without a playbook.

Brand Assets

• Main README banner: assets/brand/codex-coach-banner.png
• Wide logo/social preview: assets/brand/codex-coach-logo.png
• Square icon: assets/brand/codex-coach-icon.png