docs: add Claude Desktop + Codex desktop install paths#509
Conversation
There was a problem hiding this comment.
Pull request overview
Adds installation/verification guidance for Claude Desktop and Codex Desktop to the README, plus two new paste-ready diagnostic scripts to help beta testers report actionable desktop-specific failures (MCP config, hooks, logs, runtime issues).
Changes:
- README: document Claude Desktop MCP-only install flow (manual
claude_desktop_config.json), verification prompts, troubleshooting, and a diagnostic script link. - README: expand Codex section to cover both CLI + desktop, split verification instructions, and add a diagnostic script link.
- Scripts: add
ctx-debug-claude-desktop.shandctx-debug-codex-desktop.shto generate redacted markdown reports for issue filing.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.
| File | Description |
|---|---|
README.md |
Adds Claude Desktop install/verify/troubleshooting section and updates Codex docs to cover desktop + links to new debug scripts. |
scripts/ctx-debug-claude-desktop.sh |
New Claude Desktop-focused diagnostic script (config, PATH, logs) with redaction and report generation. |
scripts/ctx-debug-codex-desktop.sh |
New Codex Desktop/CLI diagnostic script (config, hooks, routing, sessions/logs) with redaction and report generation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Use Python for JSON parsing (preinstalled on macOS) | ||
| json_get() { | ||
| local file="$1" path="$2" | ||
| python3 -c "import json,sys | ||
| try: | ||
| d = json.load(open('$file')) | ||
| keys = '''$path'''.split('.') | ||
| for k in keys: | ||
| if k: d = d[k] | ||
| if isinstance(d, list): d = ' '.join(map(str, d)) | ||
| print(d) | ||
| except (KeyError, TypeError, FileNotFoundError, json.JSONDecodeError): | ||
| print('')" 2>/dev/null |
| -e 's/(ghp_[A-Za-z0-9]{4})[A-Za-z0-9]+/\1***REDACTED***/g' \ | ||
| -e 's/("(token|secret|password|apiKey|api_key|auth|authorization)"[[:space:]]*:[[:space:]]*")([^"]{4})[^"]*/\1\3***REDACTED***/g' \ | ||
| -e 's|(https?://[^:]+:)[^@]+(@)|\1***REDACTED***\2|g' |
| # Tee output to both terminal and report file. | ||
| exec > >(tee "$OUT") |
| 3. In Claude Desktop, go to Settings → Projects → New Project. Paste the contents of `node_modules/context-mode/configs/claude-code/CLAUDE.md` into the **Custom Instructions** field. Without this, the model falls back to raw `Bash`/`Read` for ~40% of operations. | ||
|
|
| echo "## 5. hooks.json" | ||
| HOOKS="$CODEX_DIR/hooks.json" | ||
| if [[ -r "$HOOKS" ]]; then | ||
| ok "hooks.json exists" | ||
| if python3 -m json.tool "$HOOKS" >/dev/null 2>&1; then | ||
| ok "valid JSON" | ||
|
|
||
| # Inspect each event | ||
| EVENTS=("PreToolUse" "PostToolUse" "SessionStart" "UserPromptSubmit" "Stop") | ||
| for ev in "${EVENTS[@]}"; do | ||
| HAS="$(python3 -c "import json; d=json.load(open('$HOOKS')); print('yes' if '$ev' in d.get('hooks',{}) else 'no')" 2>/dev/null)" | ||
| if [[ "$HAS" == "yes" ]]; then | ||
| ok "$ev hook registered" | ||
| else | ||
| wn "$ev hook missing — context-mode session continuity may degrade." | ||
| fi | ||
| done |
| # Extract a TOML scalar (best-effort, handles `key = "value"` and `key = value`). | ||
| toml_get() { | ||
| local file="$1" section="$2" key="$3" | ||
| awk -v sec="[$section]" -v k="$key" ' | ||
| BEGIN { in_section = 0 } | ||
| /^\[/ { in_section = ($0 == sec); next } | ||
| in_section && $1 == k { | ||
| sub(/^[^=]*=[[:space:]]*/, "") | ||
| gsub(/^"|"$/, "") | ||
| exit | ||
| } | ||
| ' "$file" 2>/dev/null | ||
| } | ||
|
|
||
| # Check whether a TOML section exists. | ||
| toml_has_section() { | ||
| grep -q "^\[$1\]" "$2" 2>/dev/null | ||
| } |
| fi | ||
| if [[ -d "$CODEX_DIR/log" ]]; then | ||
| ok "log dir present" | ||
| LATEST_LOG="$(find "$CODEX_DIR/log" -name '*.log' -type f 2>/dev/null | head -1)" |
| -e 's/(ghp_[A-Za-z0-9]{4})[A-Za-z0-9]+/\1***REDACTED***/g' \ | ||
| -e 's/("(token|secret|password|apiKey|api_key|auth|authorization)"[[:space:]]*:[[:space:]]*")([^"]{4})[^"]*/\1\3***REDACTED***/g' \ | ||
| -e 's|(https?://[^:]+:)[^@]+(@)|\1***REDACTED***\2|g' |
|
|
||
| # ─── start ──────────────────────────────────────────────────────────────────── | ||
|
|
||
| exec > >(tee "$OUT") |
murataslan1
force-pushed
the
docs/readme-desktop-platforms
branch
from
0d28f85 to
85e0852
Compare
Claude Desktop's /plugin slash command isn't available in the desktop UI (verified empirically), so plugin marketplace install isn't a viable path there. README adds an MCP-only install block via claude_desktop_config.json with three verification prompts and troubleshooting for PATH and ABI mismatch. Codex CLI and the Codex desktop app share ~/.codex/, so the existing install steps already cover both. Header now reads "Codex CLI + Codex Desktop", desktop app appears in prerequisites, and Verify splits into CLI (terminal) and Desktop (chat prompts). Extends scripts/ctx-debug.sh with desktop-specific checks instead of introducing parallel scripts: Claude.app / Codex.app version detection, claude_desktop_config.json (macOS + Windows paths), and a hardcoded-nvm-path warning for hook command paths that silently die after \`nvm install <newer>\`. README diagnostic lines point to the single canonical script.
murataslan1
force-pushed
the
docs/readme-desktop-platforms
branch
from
85e0852 to
ecb318e
Compare
|
Amended after a closer look at scripts/ctx-debug.sh — original draft added two parallel scripts (ctx-debug-claude-desktop.sh + ctx-debug-codex-desktop.sh), but ~70% of the Codex one duplicated existing sections (Adapter Detection, Config Files, Hook Validation). Reshaped to extend the canonical script instead. Three minimal additions to scripts/ctx-debug.sh:
Verified on macOS 15.5: all three checks fire. The nvm warn caught a real config gap in my own setup (Codex hooks.json + Claude settings.json both had hardcoded paths from an older nvm version). Smoke test ( Diff is now +128 / -5 (was +654 / -4). README diagnostic lines point to the single canonical Related to #45 — adds the OS/platform install reference beta testers were missing for the two desktop apps. |
murataslan1
force-pushed
the
docs/readme-desktop-platforms
branch
from
e3691b6 to
ab5360a
Compare
The README diagnostic line uses `bash <(curl -fsSL .../ctx-debug.sh)`. That lands SCRIPT_DIR in /dev/fd so SCRIPT_DIR/.. resolves to /dev — not a context-mode checkout. The script then reports 17 false-negative failures (package.json, build/, hooks/*.mjs, server.bundle.mjs, better-sqlite3, FTS5, etc.) which look like a broken install. Now falls back to common install locations after the existing detection: 1. ~/.claude/plugins/cache/context-mode/context-mode/<latest>/ 2. $(npm root -g)/context-mode 3. /opt/homebrew/lib/node_modules/context-mode 4. /usr/local/lib/node_modules/context-mode Each candidate is validated by checking that package.json declares "name": "context-mode" before adopting it. Verified locally on macOS: 17 failures collapse to 1 (unrelated -shm orphan check).
murataslan1
force-pushed
the
docs/readme-desktop-platforms
branch
from
ab5360a to
9782e31
Compare
|
Two updates, one of them a recovery note — sorry in advance. Recovery note: Your The follow-up fix: Empirical testing surfaced a real UX problem with the README's diagnostic line.
Each candidate is validated by checking the package.json Verified locally on macOS 15.5: |
|
Quick note for context: this PR is purely docs + debug-script and is orthogonal to #547 — no Codex hook matchers or I separately audited #547 against https://gist.github.com/murataslan1/8c2196c122b91c7cbb79d3454815436e Happy to keep that audit work in a separate PR if it ever finds something the existing tests don't already cover. This one stays scoped to the README and debug-script changes. |
Why
Claude Desktop and the Codex desktop app weren't covered in the README.
/pluginslash command isn't available in Claude Desktop UI (verified empirically — the model returns/plugin isn't available in this environment.), so the plugin marketplace install isn't a viable path there.What's in
claude_desktop_config.json, three verification prompts, troubleshooting (PATH, ABI mismatch), npx-on-demand alternative.~/.codex/, so the existing install steps already cover both.scripts/ctx-debug-claude-desktop.sh— checks Claude.app,claude_desktop_config.json, MCP log (recent failures only), better-sqlite3 ABI, plugin cache cohabitation.scripts/ctx-debug-codex-desktop.sh— checks Codex.app,~/.codex/config.toml,hooks.json(per-event registration + hardcoded-nvm-path detection), AGENTS.md routing, session/log dirs.Both scripts are read-only, redact secrets, and write a paste-ready markdown report to
~/ctx-debug-{claude,codex}-desktop-<ts>.md.Verified empirically
Smoke-test prompt (
ctx_doctor+ctx_execute+ctx_batch_execute+ctx_stats) ran clean on both desktops. Debug scripts validated against the same setup:ctx-debug-claude-desktop.sh: 9 PASS / 0 FAIL / 0 WARNctx-debug-codex-desktop.sh: 17 PASS / 0 FAIL / 2 WARN — the warnings caught a real config gap (UserPromptSubmit + Stop hooks missing in the tester's~/.codex/hooks.json), which is exactly the beta-tester signal these scripts are meant to surface.Notes for review
curlURLs targetmksglu/context-mode/mainand only go live post-merge. For pre-merge review, the scripts can be run directly from a PR branch checkout.