codex-insights

中文说明 / Chinese README

codex-insights is a Codex skill repository. It packages the insights skill plus bundled Python scripts that analyze local Codex session artifacts and generate a structured report.

Why This Repo

This repository is designed for Codex skill distribution, not as a generic Python package. The main unit of reuse is the insights/ skill folder, which you can drop into ~/.codex/skills/.

Repository Layout

insights/
├── SKILL.md
├── agents/openai.yaml
└── scripts/
    ├── codex_insights.py
    └── run_insights.py

Install As A Skill

Copy the insights/ folder into your Codex skills directory:

mkdir -p ~/.codex/skills
cp -R insights ~/.codex/skills/

After that, Codex can trigger the skill when the task matches the description in insights/SKILL.md.

Trigger From Codex

Example prompts that should trigger this skill:

• 使用 $insights 技能，分析最近 7 天的本地 Codex 会话
• 看下我最近一个月的 Codex 工作模式，有没有重复返工
• Generate a local insights report for my recent Codex sessions

Run The Bundled Script Directly

From the skill directory:

python3 scripts/run_insights.py --days 30 --max-sessions 50

Examples:

python3 scripts/run_insights.py --lang en --days 7 --max-sessions 20
python3 scripts/run_insights.py --format html --open
python3 scripts/run_insights.py --output ./reports/codex-insights

What The Skill Reads

By default the bundled script reads:

• ~/.codex/history.jsonl
• ~/.codex/session_index.jsonl
• ~/.codex/sessions/**/*.jsonl

You can override those paths with flags:

• --history-path
• --session-index-path
• --sessions-root

Other useful flags:

• --days
• --max-sessions
• --lang
• --format
• --output
• --open

Output

Reports are written to ./reports/ by default and include:

1. Scope
2. Summary
3. Session Overview
4. Repeated Patterns
5. Frictions
6. Effective Behaviors
7. Recommendations
8. Evidence Appendix

A synthetic example is available at examples/sample-report.md.

Development

Run tests:

python3 -m unittest discover -s tests -v

Privacy

This skill works on local files. Review generated reports before sharing them externally, because session prompts, paths, and environment details may be sensitive.