Codex VS Code Problems

codex-vscode-problems exports live VS Code Problems diagnostics to a local cache and exposes them through an MCP server that can refresh, inspect, and summarize snapshots without rerunning every analyzer from scratch.

This repo ships three surfaces from one source of truth:

• extension/: the VS Code bridge that writes snapshots plus incremental refresh status.
• mcp/: the npm package codex-vscode-problems-mcp.
• skill/: an optional local skill for setups that explicitly want skill-based routing hints.

Install

1. Install the extension from a GitHub release

Download the current VSIX from the latest GitHub release, then install it:

gh release download --repo CrownOpsEng/codex-vscode-problems --pattern "codex-vscode-problems-*.vsix" --dir /tmp/codex-vscode-problems
code --install-extension /tmp/codex-vscode-problems/codex-vscode-problems-*.vsix --force

2. Register the MCP server from npm

This is the canonical Codex registration command:

codex mcp add vscode-problems --env "CODEX_VSCODE_PROBLEMS_DIR=~/.cache/codex-vscode-problems" -- npx -y codex-vscode-problems-mcp

3. Optional local skill sync

/home/user/Code/codex-vscode-problems/scripts/install_local.sh --mode consumer --sync-skill

The skill is optional. The canonical integration path is the MCP server itself, and agents can use the MCP without any repo-local fallback layer. Use --sync-skill only if your setup explicitly relies on local skills for routing hints or pinned instructions.

Contributions

External contributions are accepted under CLA.md. Contributors retain ownership of their work, while the CLA ensures the project can continue to distribute contributions under MIT and, if needed, under additional licenses.

Contributor Workflow

Use contributor mode when you are working from a local clone and want Codex to run the local MCP server directly:

/home/user/Code/codex-vscode-problems/scripts/install_local.sh --mode contributor

Contributor mode:

• packages and installs the local VSIX build
• registers vscode-problems against the local node mcp/src/server.mjs entrypoint

If you also want the optional local skill:

/home/user/Code/codex-vscode-problems/scripts/install_local.sh --mode contributor --sync-skill

Local path registration is development-only. The published and documented install path is npm-based.

Runtime Layout

The extension writes one workspace snapshot plus one stable workspace status file under ~/.cache/codex-vscode-problems/ by default:

• workspace-<id>.json: current snapshot
• workspace-<id>.status.json: latest refresh state, target availability, and last success/failure
• requests/refresh-<id>.json: MCP-to-extension refresh requests
• responses/refresh-<id>.json: incremental per-request refresh status

MCP Tools

Read tools:

• problems_status
• problems_targets
• problems_summary
• problems_list
• problems_by_file
• problems_sources
• problems_files

Refresh tool:

• problems_refresh

problems_refresh accepts targets?: string[] and the legacy sources?: string[] alias. Target inputs may be:

• canonical keys like ruff
• diagnostic sources like Ruff
• extension ids like charliermarsh.ruff

Recommended Agent Flow

1. Start with problems_targets to request capabilities and see which analyzers are refreshable versus merely observable.
2. Read problems_status before starting another refresh so in-progress, skipped, failed, or stuck scanners are visible. On a first run it may return an empty state rather than an error.
3. Use problems_summary, problems_list, problems_by_file, or problems_files against the existing snapshot first when it already covers the analyzer scope you need.
4. Call problems_refresh only when a fresh pull is needed because the snapshot is missing, stale for the task, or missing required analyzer coverage.
5. Prefer targeted refreshes. A successful targeted refresh only guarantees freshness for the requested targets, not for every analyzer in the workspace.
6. If a narrow refresh comes back clean and you need broader confidence, recheck problems_status or request a broader refresh intentionally instead of assuming the rest of the workspace is current.
7. If a scanner is stuck, retry a narrow problems_refresh for that target before escalating to heavier CLI checks or window reload.

Refresh Semantics

The bridge tracks request states:

• queued
• accepted
• running
• completed
• failed
• timed_out
• stuck

Per-target states are tracked independently:

• pending
• restarting
• waiting_for_diagnostics
• completed
• skipped
• unsupported
• failed

Per-target completion is inferred from command execution plus diagnostic settling. The bridge reports that explicitly instead of pretending VS Code exposed an authoritative completion signal.

To reduce noisy analyzer churn, the extension also applies two safety rails during refresh:

• only one refresh may actively restart analyzers for a workspace at a time
• slow targets such as Pylance are cooldown-protected for codexProblemsBridge.slowTargetRestartCooldownMs milliseconds after a restart, with 15000 as the default

Development

Run tests:

npm test

Run the full packaging and release checks:

npm run release:check

Prepare an isolated VS Code smoke environment with the packaged bridge VSIX without interrupting your current window:

npm run smoke:vscode

Launch that isolated window only when you want it to open and wait for a fresh status file:

npm run smoke:vscode:launch

Package just the VSIX:

npm run package:extension

Pack the MCP npm tarball:

npm run package:mcp

Release Shape

GitHub is the release hub:

• source of truth repo: CrownOpsEng/codex-vscode-problems
• VS Code extension: GitHub release VSIX asset
• MCP server: npm package codex-vscode-problems-mcp

Release automation:

• PR CI runs tests plus MCP/VSIX packaging smoke checks
• tag releases run tests, package the VSIX, publish the npm package, create a GitHub release, and upload the VSIX asset
• release verification checks version sync, manifest commands, README install examples, and VSIX archive contents before publishing

License

Source code in this repository is available under the MIT License.

The project also uses CLA.md for incoming contributions. The CLA is not required by MIT itself, but it keeps contributor ownership explicit while granting the maintainer the rights needed to keep the project distributable under MIT and to handle future relicensing if ever needed.

Troubleshooting

Stale snapshot, but still maybe useful

Use problems_status first. The bridge reports recent target-level refresh detail alongside stale snapshot errors so agents can decide whether old-but-usable data is acceptable before they request a new refresh.

Stale installed extension

If the refresh command is missing or status files never appear, reinstall the current GitHub release VSIX. Older local builds can remain installed under a different extension id.

Refresh acknowledgement failures

If problems_refresh times out before acknowledgement:

• confirm VS Code is open on the workspace you are targeting
• confirm the bridge extension is installed and enabled
• confirm the cache directory matches CODEX_VSCODE_PROBLEMS_DIR
• check for workspace-*.status.json files to see whether the extension is writing any bridge state at all

Agent-safe recovery when refresh is partial or misleading

Prefer these non-disruptive steps:

• use problems_targets first when you need to confirm whether the analyzer is refreshable at all
• use problems_status to inspect the latest per-target state without starting another refresh
• retry problems_refresh with one target at a time to isolate the analyzer that is slow, stuck, or not republishing
• use problems_by_file or problems_files when workspace-wide counts do not match the file or subtree you just changed

Do not assume that restarting Pylance republishes Ruff, pylint, mypy, or markdownlint diagnostics. A targeted refresh only asks the selected analyzer to publish again.

Do not interpret accepted, running, pending, or waiting_for_diagnostics as a clean result. Those states mean the requested scope is still in flight.

If a second refresh is rejected as already in progress, or a slow target is skipped because it ran recently, that is intentional bridge behavior to avoid stacked restarts and stale spinner-heavy editor notifications.

markdownlint diagnostics remain readable through the snapshot, but the current extension stack does not expose a deterministic bridge refresh target for markdownlint, so agents should treat it as observable rather than target-refreshable.

Development versus published registration

If Codex is still pointing at a brittle local path registration, rerun one of:

/home/user/Code/codex-vscode-problems/scripts/install_local.sh --mode contributor
/home/user/Code/codex-vscode-problems/scripts/install_local.sh --mode consumer