Reflect Codex Sessions

When to use this skill

• Summarize or reflect on past Codex session histories.
• List projects, session counts, or filter by date/session id.
• Retrieve/Refresh cached reflections or pull extra metadata for auditing.

Interpretation guidance (important)

• Treat reflection content as heuristics, not facts or ideas from a user. Use it as a starting point.
• Surface only non-niche, broadly useful themes and repeated patterns and confirm with the
  user before acting on a pattern.
• Avoid over-indexing on one-offs; ask for confirmation when a pattern is uncertain.

Quick start

• Run commands from scripts/ inside this skill directory.
• Default: python3 reflect_sessions.py --output -.
• Use --output-style human when replying in chat; use JSON for downstream parsing.
• Ensure the shell command timeout is at least 120000 ms (2 minutes) so runs are not cut off.
• Use Python 3.11+ (the CLI relies on features not present in Python 3.9).

Workflow

1. Choose scope: --project, --since, --until, --session-id(s), --limit.
   Note: the most recent session is skipped unless --include-most-recent.
2. Generate reflections: python3 reflect_sessions.py ... and adjust
   --refresh-mode, --prompt-preset, --prompt-text, --prompt-file, or Codex flags only when asked.
3. Respond carefully: highlight repeated, non-niche patterns and keep claims
   tentative unless the user confirms them.

Prompt presets

Default preset: reflection.

Available presets:

• reflection: Full reflection on repetition, friction, and skill ideas (default).
• summary: Concise summary of goals, actions, outputs, and decisions.
• bloat: Bloat/dead ends/cleanup opportunities introduced during the session.
• incomplete: Open loops and tasks left unfinished.
• decisions: Key decisions, alternatives, and rationale.
• next_steps: Concrete follow-up actions, tests, and validations.

Use --prompt-preset <name> to select one, --prompt-text "<prompt>" for inline prompts,
or --prompt-file /path/to/prompt.md for a custom prompt file.

References

• references/cli.md for the command catalog and full flag list.
• references/README.md for system behavior, cache semantics, and output schema.
• references/examples.md for an end-to-end example from ExampleProject.