Codex OSS Lens

Codex OSS Lens is a local-first usage and workflow dashboard for OpenAI Codex maintainers. It reads Codex rollout JSONL files from ~/.codex/sessions/ and turns them into a small browser UI for quota windows, workspace load, model mix, recent sessions, and observed token signals.

The goal is to help open-source maintainers answer practical questions before a review, release, or triage sprint:

• Which repositories are consuming most Codex attention?
• Are 5-hour or weekly quota windows close to saturation?
• Which models are used across maintenance work?
• How many turns and tool calls are common in recent sessions?
• Which branch/commit was active during a Codex session?
• Is the recent workload implementation, review, triage, release, or security-oriented?
• Which Codex workflows deserve API-credit automation next?

Why this exists

Existing Codex usage visibility is fragmented across CLI sessions, plan windows, and local JSONL files. Maintainers need a fast way to understand where Codex is helping, where it is stuck, and which maintenance workflows should be automated or improved.

Codex OSS Lens keeps that analysis local. It does not upload prompts, code, logs, or repository paths to a hosted service.

Try the published package

npx -y codex-oss-lens@latest serve --demo

The CLI is published on npm as codex-oss-lens. For a global install:

npm install -g codex-oss-lens
codex-oss-lens serve --demo

For a registry smoke check without opening the UI:

npm exec --yes --package codex-oss-lens@latest -- codex-oss-lens demo

Current status

Area	Status
Local JSONL scan	Available
Dashboard preview	Available
Weekly Markdown export	Available
Path redaction	Basename, hash, or private full path
Git branch/commit context	Codex payload and local .git fallback
Workflow classification	Metadata-only heuristics
API summary payload	Aggregate-only dry run available
GitHub outcomes	Optional issue/PR metadata import through gh
Outcome links	Local branch-to-PR matching
Maintainer brief	Shareable evidence pack generation
Brief audit	Share-readiness score and next actions
Redaction check	Leak scan for shareable artifacts
Brief comparison	Day-over-day maintainer evidence deltas
Submission readiness	One-command go/no-go report
API credit plan	Prioritized privacy-first API automation plan
Activity timeline	Chronological maintainer activity evidence
Evidence index	Reviewer-friendly artifact index in JSON, Markdown, and HTML
Maintainer scorecard	Weighted application readiness score with next actions
Submission pack	One-command application evidence folder generation
Form draft	Copy-ready Korean OSS support application answers
Pack validation	Required-file, score, readiness, and privacy validation
NPM publish check	Login, registry, package metadata, and OTP guidance
Published install smoke	npm exec verification for the published CLI
Published package	Available on npm as codex-oss-lens
Published smoke CI	Scheduled and manual GitHub Actions verification

Quick start

npm install
npm test
npm run serve

Then open http://127.0.0.1:5057.

The same UI can run from the published npm package:

npx -y codex-oss-lens@latest serve --demo

To write a report that can be opened in the static UI:

node src/cli.js scan --out examples/codex-lens-report.json

Workspace paths are redacted by default. For stable anonymous workspace ids:

node src/cli.js scan --redaction hash --out shareable-report.json

For a private local report with full paths:

node src/cli.js scan --show-paths --out private-report.json

To export a shareable weekly maintainer summary:

node src/cli.js weekly --out weekly-codex-report.md

To inspect the aggregate-only payload that a future API summary would send:

node src/cli.js api-payload --out api-payload.dry-run.json

To import public GitHub issue and pull request metadata for local comparison:

node src/cli.js github-import --repo dbunk903/codex-oss-lens --out github-outcomes.json

To link a scan report with imported GitHub outcomes:

node src/cli.js link-outcomes --report report.json --github github-outcomes.json --out linked-outcomes.json

To check local readiness without exposing rollout filenames or prompt content:

node src/cli.js doctor

To generate a full local evidence pack for review or OSS support applications:

node src/cli.js brief --repo dbunk903/codex-oss-lens --out-dir codex-brief

To audit whether that evidence pack is ready to share:

node src/cli.js audit --manifest codex-brief/manifest.json --out codex-brief/audit.json

To scan the generated artifacts for accidental paths, rollout filenames, raw-log markers, or likely secrets:

node src/cli.js redact-check codex-brief --out codex-brief/redact-check.json

To compare two maintainer briefs across days:

node src/cli.js compare-briefs --base old-brief/manifest.json --head codex-brief/manifest.json --markdown brief-delta.md

To combine audit, redaction, and optional baseline comparison into one submission report:

node src/cli.js readiness --manifest codex-brief/manifest.json --base old-brief/manifest.json --markdown readiness.md

To turn a scan report into a prioritized API-credit implementation plan:

node src/cli.js api-plan --report codex-brief/scan-report.json --markdown api-plan.md

To generate a chronological activity timeline from a scan report:

node src/cli.js timeline --report codex-brief/scan-report.json --markdown timeline.md

To compose a reviewer-facing evidence index:

node src/cli.js evidence-index --manifest codex-brief/manifest.json --readiness readiness.json --api-plan api-plan.json --timeline timeline.json --html evidence-index.html

To produce a weighted maintainer application scorecard:

node src/cli.js scorecard --manifest codex-brief/manifest.json --readiness readiness.json --api-plan api-plan.json --timeline timeline.json --markdown scorecard.md

To generate the full application evidence folder in one command:

node src/cli.js submission-pack --repo dbunk903/codex-oss-lens --out-dir codex-submission-pack

To generate copy-ready Korean form answers from the same evidence:

node src/cli.js form-draft --manifest codex-submission-pack/manifest.json --readiness codex-submission-pack/readiness.json --api-plan codex-submission-pack/api-plan.json --scorecard codex-submission-pack/scorecard.json --repo https://github.com/dbunk903/codex-oss-lens --markdown form-draft.md

To validate a generated submission pack before sharing it:

node src/cli.js pack-validate codex-submission-pack --markdown pack-validation.md

To check npm publish readiness, including login, package metadata, registry status, and OTP command guidance:

node src/cli.js publish-check --markdown publish-check.md

After publishing, verify the public package can install and run through npm exec:

node src/cli.js install-smoke --package codex-oss-lens --version latest --markdown install-smoke.md

To preview without local Codex logs:

node src/cli.js serve --demo

CLI

codex-oss-lens scan [--codex-home ~/.codex] [--limit 250] [--out report.json]
codex-oss-lens weekly [--codex-home ~/.codex] [--limit 250] [--out weekly.md]
codex-oss-lens api-payload [--codex-home ~/.codex] [--limit 250] [--out payload.json]
codex-oss-lens github-import --repo owner/name [--limit 50] [--out github-outcomes.json]
codex-oss-lens link-outcomes --report report.json --github github-outcomes.json [--out linked.json]
codex-oss-lens doctor [--codex-home ~/.codex] [--out doctor.json]
codex-oss-lens brief [--codex-home ~/.codex] [--repo owner/name] [--out-dir codex-brief]
codex-oss-lens audit --manifest codex-brief/manifest.json [--out audit.json]
codex-oss-lens redact-check <file-or-dir> [--out redact-check.json]
codex-oss-lens compare-briefs --base old/manifest.json --head new/manifest.json [--out compare.json] [--markdown compare.md]
codex-oss-lens readiness --manifest codex-brief/manifest.json [--path codex-brief] [--base old/manifest.json] [--out readiness.json] [--markdown readiness.md]
codex-oss-lens api-plan --report scan-report.json [--out api-plan.json] [--markdown api-plan.md]
codex-oss-lens timeline --report scan-report.json [--out timeline.json] [--markdown timeline.md]
codex-oss-lens scorecard --manifest manifest.json [--readiness readiness.json] [--api-plan api-plan.json] [--timeline timeline.json] [--out scorecard.json] [--markdown scorecard.md]
codex-oss-lens evidence-index --manifest manifest.json [--readiness readiness.json] [--api-plan api-plan.json] [--timeline timeline.json] [--scorecard scorecard.json] [--form-draft form-draft.json] [--out evidence-index.json] [--markdown evidence-index.md] [--html evidence-index.html]
codex-oss-lens submission-pack [--codex-home ~/.codex] [--repo owner/name] [--out-dir codex-submission-pack] [--demo]
codex-oss-lens form-draft --manifest manifest.json [--readiness readiness.json] [--api-plan api-plan.json] [--scorecard scorecard.json] [--repo url] [--release-url url] [--out form-draft.json] [--markdown form-draft.md]
codex-oss-lens pack-validate <submission-pack-dir> [--min-score 75] [--out pack-validation.json] [--markdown pack-validation.md]
codex-oss-lens publish-check [--package-json package.json] [--out publish-check.json] [--markdown publish-check.md]
codex-oss-lens install-smoke [--package codex-oss-lens] [--version latest] [--bin codex-oss-lens] [--out install-smoke.json] [--markdown install-smoke.md]
codex-oss-lens serve [--codex-home ~/.codex] [--port 5057] [--demo]
codex-oss-lens demo [--out report.json]

Data model

Codex OSS Lens scans files matching:

~/.codex/sessions/**/rollout-*.jsonl

It extracts:

• session metadata: id, start/end timestamps, workspace, model
• workflow metrics: turn count, tool-call count, duration
• Git metadata: branch and short commit when Codex logs or local .git metadata provide it
• workflow classification: implementation, review, triage, release, security, or unknown
• token signals when available in token_count or usage payloads
• quota windows from rate_limits.primary and rate_limits.secondary

Older Codex logs may not contain token usage details. In that case the dashboard still shows session, workspace, model, turn, tool, and quota-window data.

Full workspace paths are redacted unless --show-paths is passed. Use --redaction hash when a report needs stable workspace identities without exposing names.

See report schema for the generated JSON shape.

Privacy posture

• Raw rollout JSONL stays on the local machine.
• Shareable exports redact workspace paths by default.
• Workflow labels are derived from metadata such as branch names, event categories, and counts.
• Future API-backed features should start with a dry-run payload and explicit opt-in.

Roadmap

• Redaction controls for workspace path display
• Cost estimation profiles by model and plan
• Exportable weekly maintainer report
• GitHub issue/PR labels to connect Codex usage with maintenance outcomes
• Optional OpenAI API summarization of local-only aggregate metrics

See API-credit workflow for the privacy-first API plan. See npm publishing for package verification steps. See maintainer use cases for practical OSS workflows this tool supports.

Maintainer Brief

codex-oss-lens brief creates a local folder containing:

• brief.md and brief.html
• scan-report.json
• weekly-report.md
• api-payload.dry-run.json
• doctor.json
• optional github-outcomes.json and linked-outcomes.json when --repo is supplied

This is the recommended artifact for sharing a privacy-preserving snapshot of Codex maintainer activity.

Run audit, redact-check, and compare-briefs before sharing repeated evidence packs. These commands make the share-readiness score, privacy scan, and day-over-day deltas explicit instead of leaving them as manual review notes.

For application workflows, readiness combines those checks into a single go/no-go report, and api-plan converts aggregate scan data into a privacy-first API credit implementation sequence. Use timeline to show chronological maintenance activity and evidence-index to package the generated files into a reviewer-facing starting point. Use scorecard for a weighted readiness score and submission-pack when you want the whole application evidence folder generated in one pass. Use form-draft to keep Korean application answers within character limits, then run pack-validate as the final local sharing gate. Use publish-check before npm release attempts and install-smoke after release to prove the public package installs and runs.

Contributing

See CONTRIBUTING.md. Bug reports and integration requests are welcome, especially examples from maintainers using Codex across multiple repositories.

License

MIT