# trace-to-skill

> Open-source CLI and GitHub Action for Codex-ready repository maintenance: turn failed AI coding-agent runs into reusable AGENTS.md rules, SKILL.md workflows, privacy-safe traces, and eval gates.

Canonical repository: https://github.com/grnbtqdbyx-create/trace-to-skill
NPM package: https://www.npmjs.com/package/trace-to-skill
Latest release: https://github.com/grnbtqdbyx-create/trace-to-skill/releases/latest
License: Apache-2.0
Runtime: Node.js 20+

## What this project is

`trace-to-skill` helps open-source maintainers adopt Codex and other coding agents safely. It focuses on maintainer pain points:

- agents claiming completion without test/build proof
- failed tests hidden behind optimistic summaries
- Codex remote compact task failures such as `/compact` or auto-compaction hitting `responses/compact` stream disconnects, child-process timeout messages, provider timeout workarounds, and long-thread recovery loss
- Codex context compaction failures such as remote compact stream disconnects, `context_length_exceeded`, stuck automatic compaction, and `unknown variant auto`
- Codex Windows helper path failures such as bundled `rg.exe`, `node_repl.exe`, Browser, Chrome, or Computer Use helpers resolving through blocked WindowsApps/MSIX package paths, missing `%LOCALAPPDATA%\OpenAI\Codex\bin`, broken LocalCache helper bins, `CodexSandboxUsers` ACL gaps, EFS/copyfile failures, and `missing-helper-path`
- Codex patch safety failures such as `apply_patch` accepting `*** Add File` for an existing path, misleading `A <path>` summaries, symlink target replacement, and missing preflight checks before generated patches touch the workspace
- Codex sandbox and permission failures such as setup refresh errors, `os error 740`, `CodexSandboxOffline` ownership drift, ACL denial, and approval-mode downgrades
- Codex config drift such as Preferences `Unable to save`, `configVersionConflict`, legacy `profile` / `[profiles.*]` config, Speed/Fast persistence drift between `config.toml` and `.codex-global-state.json`, stale model pins, missing permission profiles, Windows elevated sandbox mode, plugin cache drift, and MCP approval sprawl
- Codex auth and connectivity failures such as `token_exchange_failed`, `auth.openai.com/oauth/token`, missing `ca-certificates`, proxy or MITM TLS behavior, IPv6 fallback problems, Cloudflare challenge responses, and ChatGPT stream disconnects
- Codex mobile and remote-control route health failures such as `Waiting for desktop`, `Directory Unavailable`, stale listeners on `127.0.0.1:14567`, stale `server_name` enrollment, empty backend environments, and incomplete helper bundles
- Codex MCP runtime failures such as cancelled non-interactive approvals, `request_user_input is not supported in exec mode`, dropped namespace or `serverName` metadata, `unsupported call: mcp__...__...`, and closed `StdioServerTransport` sessions
- Codex Streamable HTTP MCP failures where Penpot, n8n, DingTalk, or another HTTP/SSE MCP server initializes but fails JSON-RPC parsing, `Content-Type: text/event-stream` handling, handshakes, OAuth gating, stale session ids, missing headers, or reconnects
- Codex hooks contract gaps where users need documented event names, config schema, blocking/async semantics, Shell/Edit/Write matcher coverage, `additionalContext`, `SessionStart`, `PreCompact`, `UserPromptSubmit`, or lifecycle coverage for guardrails and automation
- Codex hooks runtime failures where hooks duplicate, stop firing, emit stale `codex_hooks` warnings, skip Code Mode/Windows/Desktop surfaces, or become hard to manage in Hooks settings
- Codex MCP discovery and config-scope mismatches where CLI `/mcp` works but VS Code, Desktop, WSL, project `.codex/config.toml`, `CODEX_HOME`, or an older conversation exposes no `mcp__*` tools
- Codex terminal output and scrollback integrity failures where streamed lines disappear, get overwritten, truncate, duplicate, misalign, snap to the bottom, or only survive in raw logs/transcripts
- Codex subagent lifecycle failures where completed or closed agents remain visible, `thread_spawn_edges` drift, child threads crowd the recent list, `agent thread limit reached` blocks spawns, or compaction loses prior subagent IDs; `session-audit` can summarize local subagent signal counts without exposing transcripts
- Codex resume and session-state failures such as frozen resume pickers, large rollout JSONL histories, short `session_index.jsonl`, transcript-like sidebar title chunks, sluggish Desktop thread rendering, dropped recent context after resume, archived chat loading failures, and `state_5.sqlite` / `goals_1.sqlite` migration drift
- Codex file tree and workspace navigation UI failures such as `View > Toggle File Tree` doing nothing, missing folder icons, stale floating file panels, and built-in preview failures
- Codex Thinking or Working hangs after accepted turns, successful local tools, or open Responses streams with no streamed assistant follow-up
- Codex clipboard, copy/export, long paste, and generated `Pasted text.txt` attachment regressions that break prompt, `/goal`, preview/edit, or support-report workflows
- Codex deeplink, OAuth callback, notification click, browser-extension activation, mobile pairing, and `codex app <path>` launch regressions
- Codex app connector stale auth/cache regressions such as `401 Reauthentication required`, unchanged `link_*`, `isAccessible: false`, and broken `codex_apps_tools` metadata
- Codex context fork bloat and prompt-cache lineage failures where conversation forks duplicate parent transcript blocks, inflate `input_tokens`, change `prompt_cache_key`, drop cache hit rate, or leak `fork_context` subagent history into child context before new work happens
- Codex subagent prompt leakage where `spawn_agent` with `fork_turns: "none"` delivers assistant/commentary prompt envelopes, same-turn parallel children see sibling prompts, or `wait_agent`/`close_agent` completes despite the wrong child task
- Codex usage popover bucket confusion where `Usage remaining`, `5h`, weekly percentages, reset dates, percent remaining vs percent used, rolling 7-day vs calendar-week, or account/workspace/device scope are unclear
- Codex token-burn, prompt-cache collapse, and usage-drain failures such as rapid drain experiments (`1% in 4 minutes`, `22 credits`, `70% weekly in a day`), `input_tokens` / `cached_input_tokens` / `prompt_cache_key` rows, websocket reconnect cache drops, background `write_stdin` polling, idle app usage, compaction tax, retry/tool loops, cached-token-heavy turns, fast-mode drift, subagent fan-out, and unclear usage attribution; use `usage-doctor` for confidence-ranked attribution buckets
- Codex process evidence packaging for Windows PowerShell/pwsh CIM polling, high-CPU helpers, stale process-manager entries, and renderer runaways
- Codex usage reset schedule drift such as weekly reset dates moving, `reset_at` jumping, saved usage disappearing, outage compensation resets changing the anchor, and `/status` disagreeing with enforcement
- Codex usage evidence packaging for scattered `/status`, reset-table, usage-limit, token-total, prompt-cache, cached-input, and orchestration-overhead snippets
- Codex usage receipts that separate backend quota-window percentages, bounded drain experiments, local token totals, and overhead signals such as background polling, compaction loops, retry/tool loops, subagent fan-out, or idle drain
- Codex Action duplicate triage where maintainers need to confirm whether bot-suggested duplicate issues are exact duplicates or only related by platform, failure kind, labels, or surface
- Codex undo/rewind support workflows where maintainers need a local pre-agent workspace checkpoint with git diffs plus copied changed/untracked files before agent edits
- Codex resource leaks and runaway local processes such as high CPU/GPU, `Code Helper`, `Codex Helper Renderer`, orphaned shell snapshots, log floods, thinking animation GPU loops, and non-Git workspace CPU loops
- Codex quota and usage-limit mismatches where `/status` or the usage page shows remaining quota, accounts share limits unexpectedly, or 5h and weekly quotas move together
- sensitive-file access in traces, including `.env`, private keys, package auth files, cloud credentials, local databases, and production secret manifests entering agent context
- sensitive path preflight before agent runs via `sensitive-audit`, with filename/path-only detection and reviewable ignore candidates for `.agentignore`, `.aiexclude`, `.codexignore`, `.gitignore`, or sandbox profiles
- language-server readiness before agent edits via `lsp-audit`, with repo language detection, PATH checks, install hints, and evidence files for Codex LSP setup
- hallucinated files and broad over-editing
- conflicting `AGENTS.md`, `CLAUDE.md`, Cursor, Copilot, or Gemini instructions
- stale path references, missing `@file.md` includes, nested `AGENTS.md` visibility gaps, invalid UTF-8, and oversized instruction files that can make Codex follow wrong or truncated guidance
- prompt injection in issue, PR, review, discussion, check-run, commit, log, or web text
- risky MCP server capabilities, secret-bearing environment variables, broken JSON/TOML startup inputs, unresolved plugin placeholders, missing `cwd`, deprecated `codex_hooks`, missing `default_permissions` profiles, synced `projects.* trusted_level` metadata, and `mcp_servers` / `mcpServers` casing mismatches
- sharing failed agent traces without leaking tokens, emails, local paths, or hidden Unicode controls

The core loop is:

```text
failed agent run -> failure class -> evidence-backed AGENTS.md/SKILL.md suggestion -> eval gate -> keep or revise
```

## Best entry points for bots and maintainers

- README: https://github.com/grnbtqdbyx-create/trace-to-skill#readme
- Use cases: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/USE_CASES.md
- Codex duplicate audit demo: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/CODEX_DUPLICATE_AUDIT.md
- Codex Issue Radar demo: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/CODEX_ISSUE_RADAR.md
- Codex Issue Heat demo: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/CODEX_ISSUE_HEAT.md
- Codex surface support matrix: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/CODEX_SURFACE_MATRIX.md
- Codex issue map: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/CODEX_ISSUE_MAP.md
- Discovery summary: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/DISCOVERY.md
- Demo output: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/DEMO.md
- Adoption guide: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/ADOPTION_GUIDE.md
- Failure taxonomy: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/FAILURE_TAXONOMY.md
- OpenAI OSS strategy: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/OPENAI_OSS_STRATEGY.md
- OpenAI application draft: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/OPENAI_APPLICATION_DRAFT.md
- Benchmark: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/BENCHMARK.md
- Scorecard: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/docs/SCORECARD.md
- Codex readiness auditor skill: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/skills/codex-readiness-auditor/SKILL.md

## Core commands

```bash
npx trace-to-skill doctor .
npx trace-to-skill demo
npx trace-to-skill demo model-routing-mismatch
npx trace-to-skill demo thinking-hang
npx trace-to-skill demo clipboard-attachment
npx trace-to-skill demo deeplink-launch
npx trace-to-skill demo connector-auth-cache
npx trace-to-skill demo auth-verification
npx trace-to-skill demo context-fork-bloat
npx trace-to-skill demo subagent-prompt-leakage
npx trace-to-skill demo subagent-orchestration
npx trace-to-skill demo usage-bucket-confusion
npx trace-to-skill demo context-visibility
npx trace-to-skill demo remote-connection
npx trace-to-skill demo platform-availability
npx trace-to-skill demo cli-no-response
npx trace-to-skill demo mcp-discovery-mismatch
npx trace-to-skill demo mcp-streamable-http
npx trace-to-skill demo hooks-contract
npx trace-to-skill demo hooks-runtime
npx trace-to-skill demo terminal-output-integrity
npx trace-to-skill demo subagent-lifecycle
npx trace-to-skill lint-agents .
npx trace-to-skill guard-github-event "$GITHUB_EVENT_PATH"
npx trace-to-skill guard-patch ./change.patch --root .
npx trace-to-skill session-audit ~/.codex --format json
npx trace-to-skill config-audit ~/.codex --format json
npx trace-to-skill plugin-audit ~/.codex --app /Applications/Codex.app --format json
npx trace-to-skill diagnostics-bundle ~/.codex --output codex-diagnostics
npx trace-to-skill usage-doctor ./usage-notes.md --output usage-evidence.md
npx trace-to-skill process-audit ./process-notes.md --output process-audit.md
npx trace-to-skill issue-map --repo openai/codex --state all --limit 100 --output codex-issue-radar.md
npx trace-to-skill issue-heat --repo openai/codex --state open --limit 100 --window-hours 24 --output codex-issue-heat.md
npx trace-to-skill issue-heat-comment --repo openai/codex --issue-number 8 --comment-repository owner/name --dry-run
npx trace-to-skill duplicate-audit --repo openai/codex --issue 25507 --output codex-duplicate-audit.md
npx trace-to-skill duplicate-audit --repo openai/codex --issue 25507 --candidates 25391,25488 --format json
npx trace-to-skill surface-matrix --repo openai/codex --state all --limit 100 --output codex-surface-matrix.md
npx trace-to-skill issue-map-comment --repo openai/codex --issue-number 8 --comment-repository owner/name --dry-run
npx trace-to-skill init --issue-map-repo openai/codex --issue-map-state all --issue-map-limit 100
npx trace-to-skill issue-map codex-issues.json --output codex-issue-map.md
npx trace-to-skill checkpoint . --output .trace-to-skill/checkpoints/before-codex
npx trace-to-skill redact ./runs --output redacted-runs
npx trace-to-skill sensitive-audit . --format json
npx trace-to-skill sensitive-audit . --format ignore --ignore-target codexignore --output .codexignore.generated
npx trace-to-skill lsp-audit . --format json
npx trace-to-skill analyze ./runs
npx trace-to-skill codex-report ./runs --output openai-codex-issue.md
npx trace-to-skill suggest ./runs --target agents-md
npx trace-to-skill eval ./runs --threshold 80
npx trace-to-skill benchmark
npx trace-to-skill scorecard .
npx trace-to-skill init --comment --sarif
npx trace-to-skill init --issue-map-repo openai/codex --issue-map-state all --issue-map-limit 100
gh issue list --repo openai/codex --state all --limit 100 --json number,title,body,url,labels,comments,updatedAt | npx trace-to-skill issue-map - --format json
```

`issue-map` JSON and Markdown include a Maintainer Roadmap: the highest-priority failure classes, the next public artifact to build, and the exact `trace-to-skill` command that generates the supporting evidence. Use `issue-map -` when GitHub issue JSON is piped from `gh`.

## GitHub Action

```yaml
- uses: grnbtqdbyx-create/trace-to-skill@v0.1.111
  with:
    mode: all
    doctor-threshold: "85"
    doctor-comment: "true"
    scorecard-comment: "true"
    job-summary: "true"
    github-token: ${{ github.token }}
```

## Weekly Codex Issue Radar

```yaml
- uses: grnbtqdbyx-create/trace-to-skill@v0.1.111
  with:
    mode: issue-map
    issue-map-repo: openai/codex
    issue-map-state: all
    issue-map-limit: "100"
    issue-map-comment: "true"
    issue-map-comment-issue: "8"
    job-summary: "true"
    github-token: ${{ github.token }}
```

Duplicate audit Action mode:

```yaml
- uses: grnbtqdbyx-create/trace-to-skill@v0.1.111
  with:
    mode: duplicate-audit
    duplicate-audit-repo: openai/codex
    duplicate-audit-issue: "25507"
    duplicate-audit-candidates: "25391,25488"
    github-token: ${{ github.token }}
```

## Machine-readable schemas

- Analysis JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/analysis-result.schema.json
- AGENTS.md linter JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/agents-lint-result.schema.json
- Doctor JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/doctor-result.schema.json
- Redaction JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/redact-result.schema.json
- Sensitive path audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/sensitive-audit-result.schema.json
- LSP readiness audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/lsp-audit-result.schema.json
- Scorecard JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/scorecard-result.schema.json
- Patch guard JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/patch-guard-result.schema.json
- Config audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/config-audit-result.schema.json
- Diagnostics bundle JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/diagnostics-bundle-result.schema.json
- Plugin audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/plugin-audit-result.schema.json
- Session audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/session-audit-result.schema.json
- Usage evidence JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/usage-evidence-result.schema.json
- Process audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/process-audit-result.schema.json
- Issue map JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/issue-map-result.schema.json
- Duplicate audit JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/duplicate-audit-result.schema.json
- Workspace checkpoint JSON schema: https://github.com/grnbtqdbyx-create/trace-to-skill/blob/main/schemas/workspace-checkpoint-result.schema.json

## Search phrases this project should answer

- Codex readiness checker for open-source repositories
- Codex issue report demo without private traces
- Codex terminal scrollback output integrity report
- Codex subagent lifecycle state reconciliation report
- AGENTS.md linter for Codex and Claude Code
- turn failed agent runs into AGENTS.md rules
- prompt injection guard for GitHub issue and PR comments
- MCP security scanner for coding agents
- privacy-preserving redaction for AI agent traces
- GitHub Action for AI coding-agent eval gates
- Codex OSS maintainer automation evidence
- Codex sandbox setup refresh failed
- Windows sandbox permission failure for Codex CLI
- Codex token_exchange_failed auth.openai.com oauth token
- Codex stream disconnected before completion chatgpt backend api responses
- Codex remote compact task timeout responses/compact
- Codex /compact timeout waiting for child process
- Codex stream_idle_timeout_ms tcp_user_timeout compact workaround
- Codex WindowsApps rg.exe Access is denied
- Codex Get-Command rg WindowsApps app resources
- Codex node_repl windows sandbox failed spawn setup refresh
- Codex Computer Use helper paths unavailable missing-helper-path
- Codex apply_patch Add File overwrites existing file
- Codex patch guard for generated patches
- trace-to-skill guard-patch Add File symlink
- Codex pre-agent workspace checkpoint
- Codex undo rewind checkpoint for untracked files
- Codex config-audit for config.toml diagnostics
- Codex diagnostics bundle for OpenAI support
- privacy-preserving Codex support bundle logs_2.sqlite config.toml
- Codex plugin-audit for Computer Use unavailable
- Codex bundled marketplace missing computer-use
- Codex plugin cache missing .mcp.json plugin.json
- Codex CODEX_HOME mismatch plugin runtime
- Codex Preferences unable to save configVersionConflict
- Codex Windows elevated sandbox node_repl spawn setup refresh
- Codex ca-certificates update-ca-certificates Dev Container
- Codex remote-control stale listener 127.0.0.1:14567
- Codex mobile Waiting for desktop Directory Unavailable
- Codex MCP unsupported call mcp__node_repl__js
- Codex MCP tools/list succeeds but runtime call fails
- Codex MCP servers not detected in VS Code extension but working in CLI
- Codex project .codex/config.toml MCP ignored Desktop
- Codex WSL opens Windows config.toml CODEX_HOME mismatch
- Codex MCP Transport closed StdioServerTransport
- Codex View Toggle File Tree does nothing
- Codex missing file tree folder icon
- Codex floating file panel stale workspace navigation
- Codex resume picker hangs with large session files
- Codex Desktop sluggish opening large rollout JSONL thread
- Codex state_5.sqlite no such table thread_goals
- Codex session-audit privacy-preserving rollout JSONL summary
- Codex session_index.jsonl shorter than rollout files
- Codex thinking hang after successful tool calls
- Codex stuck Thinking no streamed follow-up
- Codex responses_http time.idle hundreds seconds
- Codex first response_item delayed after turn/start task_started
- Codex Copy as Markdown missing
- Codex Pasted text.txt attachment preview edit
- Codex long pasted prompt auto attachment
- Codex /goal ignores Pasted text.txt fileAttachments
- Codex deeplink OAuth callback fails
- Codex codex://oauth_callback Unable to find Electron app
- Codex Windows toast type=click&tag launches Electron error
- Codex AppUserModelID DelegateExecute protocol registration
- Codex codex app path only focuses workspace
- Codex connector 401 Reauthentication required
- Codex Apps stale link_ connector cache
- Codex codex_apps_tools codex_app_directory stale metadata
- Codex app connector isAccessible false
- Codex refresh token was revoked active session
- OpenAI Codex issue report from failed trace
- Codex bug report evidence checklist
- Codex token burn write_stdin background polling
- Codex usage evidence report
- Codex rate-limit evidence report
- Codex cached input token usage drain
- Codex prompt cache collapse evidence with prompt_cache_key, cached_input_tokens, cached_tokens, response ids, websocket reconnect, and low cache hit rate
- Codex weekly reset date changed
- Codex usage reset_at jumping
- Codex deterministic reset schedule
- Codex compaction tax weekly usage depleted
- Codex high CPU GPU resource leak shell snapshot
- Codex Code Helper Renderer runaway process
- Codex usage limit despite remaining quota
- Codex quota mismatch and rate limit debugging
- Codex exclude sensitive files from agent context
- detect .env private key credential file access in agent traces
