codex-session-insights 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# codex-session-insights
+
+Generate a report analyzing your Codex sessions.
+
+`codex-session-insights` reads your local Codex history, extracts recurring patterns from your sessions, and renders a narrative report as both HTML and JSON.
+
+![codex-session-insights screenshot](https://raw.githubusercontent.com/cosformula/codex-session-insights/main/assets/screenshot-1.png)
+
+## Quick Start
+
+Run it directly:
+
+```bash
+npx codex-session-insights
+```
+
+The default flow is:
+
+1. Read your local Codex thread index
+2. Estimate likely analysis token usage
+3. Let you confirm the plan in an interactive terminal
+4. Generate `report.html` and `report.json`
+5. Try to open the HTML report in your browser
+
+If you only want the estimate first:
+
+```bash
+npx codex-session-insights --estimate-only
+```
+
+If you already know what you want and do not want the confirmation flow:
+
+```bash
+npx codex-session-insights --yes
+```
+
+## What You Get
+
+By default the tool writes:
+
+- `~/.codex/usage-data/report.html`
+- `~/.codex/usage-data/report.json`
+
+The HTML report includes these sections:
+
+- `At a Glance`
+- `What You Work On`
+- `How You Use Codex`
+- `Impressive Things You Did`
+- `Where Things Go Wrong`
+- `Features to Try`
+- `On the Horizon`
+- `One More Thing`
+
+## Typical Usage
+
+Default run:
+
+```bash
+npx codex-session-insights
+```
+
+Estimate first, then decide:
+
+```bash
+npx codex-session-insights --days 7 --limit 20 --facet-limit 8 --estimate-only
+```
+
+Use a custom output directory:
+
+```bash
+npx codex-session-insights --out-dir ./insights-output
+```
+
+Emit JSON to stdout instead of a terminal summary:
+
+```bash
+npx codex-session-insights --stdout-json
+```
+
+Include archived threads:
+
+```bash
+npx codex-session-insights --include-archived
+```
+
+Include sub-agent threads as well as main threads:
+
+```bash
+npx codex-session-insights --include-subagents
+```
+
+Choose the report language explicitly:
+
+```bash
+npx codex-session-insights --lang zh-CN
+npx codex-session-insights --lang en
+```
+
+Use the OpenAI API instead of your local Codex CLI login:
+
+```bash
+npx codex-session-insights --provider openai --api-key $OPENAI_API_KEY
+```
+
+## Defaults
+
+Current default analysis plan:
+
+- `days`: `30`
+- `limit`: `50`
+- `facet-limit`: `20`
+- `provider`: `codex-cli`
+- `facet-model`: `gpt-5.4-mini`
+- `fast-section-model`: `gpt-5.4-mini`
+- `insight-model`: `gpt-5.4`
+- `facet-effort`: `low`
+- `fast-section-effort`: `low`
+- `insight-effort`: `high`
+
+Important behavior defaults:
+
+- Report language follows a best-effort system locale check
+- Main-thread analysis is the default; sub-agent threads are excluded unless you pass `--include-subagents`
+- The CLI shows an estimate before running in interactive terminals
+- The CLI tries to open the generated HTML report in your browser after generation
+
+## What It Reads
+
+- `~/.codex/state_*.sqlite` for the thread index
+- `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` for rollout events
+
+## Requirements
+
+- Node.js `>=18`
+- `sqlite3` available on your system `PATH`
+- Codex CLI installed if you use the default `codex-cli` provider
+
+Supported platform status:
+
+- macOS: expected to work
+- Linux: expected to work if `sqlite3` and `codex` are installed
+- Windows: not yet verified
+
+## Privacy
+
+The tool reads local Codex data from your machine.
+
+- With `provider=codex-cli`, analysis is performed through your local Codex CLI session
+- With `provider=openai`, prompts are sent through the OpenAI Responses API
+- Generated reports may contain project paths, thread titles, summaries, and other local development context
+
+Review `report.html` and `report.json` before sharing them.
+
+## Limitations
+
+- Rollout event schemas may drift across Codex versions
+- Token estimates are conservative, not billing-accurate
+- The tool is designed around Codex local storage layout and is not a generic agent log analyzer
+- Windows support is not yet verified
+
+## Advanced Overrides
+
+If you want to override the default model split manually:
+
+```bash
+npx codex-session-insights \
+  --facet-model gpt-5.4-mini \
+  --fast-section-model gpt-5.4-mini \
+  --insight-model gpt-5.4 \
+  --facet-effort low \
+  --fast-section-effort low \
+  --insight-effort high
+```
+
+To suppress browser opening:
+
+```bash
+npx codex-session-insights --no-open
+```
+
+To force browser opening:
+
+```bash
+npx codex-session-insights --open
+```
+
+## For Contributors
+
+Useful local commands:
+
+```bash
+npm install
+npm test
+npm run check
+npm run generate:test-report
+```
+
+`npm run generate:test-report` writes a deterministic sample report page to `test-artifacts/sample-report/`.

package/bin/codex-insights.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from '../lib/cli.js'
+
+runCli(process.argv.slice(2)).catch(error => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(`codex-session-insights: ${message}`)
+  process.exitCode = 1
+})