Skip to content

README.md

Latest commit

 

History

History
219 lines (142 loc) · 13.1 KB

README.md

File metadata and controls

219 lines (142 loc) · 13.1 KB
Raw

gh-auth-status-shim

A PATH-resolved gh wrapper that suppresses Claude Code Desktop's false "GitHub CLI authentication expired" toast. Addresses anthropics/claude-code#67055.

Status: workaround pending Anthropic's classifier fix. Not a replacement for gh. Uninstall when CC#67055 closes.

The bug

CC Desktop's PR poller runs gh auth status --hostname github.com with a 5-second timeoutMs. Any non-zero return — including the 5s spawn timeout itself — maps to the "auth" toast category. CC#67055 documents at least four feeder paths into the same false-positive surface:

  1. Slow gh exceeding CC's 5s (Keychain slow-read on macOS, event-loop stalls under multi-agent CPU contention).
  2. Anonymous-401 fallback when gh silently treats credentials as missing under cli/cli#13317.
  3. Network transients (timeout, connection refused, DNS hiccup).
  4. Deleted-cwd spawn failure during PR-creation race.

Items 1–3 are workaround-able with PATH interception. Item 4 spawns before the shim can run; documented as not covered.

How the shim works

User shell PATH:  ~/.local/bin/gh   →   /usr/bin/gh
                     (shim)              (real)

When something runs gh, your shell finds the shim first.

For gh auth status invocations:

  1. The shim runs the real gh auth status with an internal 4-second timeout — fits inside CC Desktop's 5s spawn-abandonment window.

  2. Classifies the outcome:

    Real gh outcome Shim verdict Why
    Exit 0, stdout "Logged in to github.com" Exit 0 Genuine success — pass through.
    Exit non-zero, stdout/stderr matches not logged in / HTTP 401 / no credentials configured Propagate (original exit code) Genuine expiry — let CC's toast fire.
    Timed out at 4s Exit 0 Transient — suppress the toast. CC abandoned the spawn at 5s anyway.
    Exit non-zero, stderr matches timeout / connection refused / could not resolve host / temporary failure / network unreachable / service unavailable / operation timed out Exit 0 Transient network — suppress.
    Exit non-zero, ambiguous output Propagate Conservative default — let CC see. Worst case: slightly delayed surfacing of a real failure; not a silent loss.

  3. Stdout and stderr are preserved through their original streams (no 2>&1 re-merge — gh historically moves auth-status output between streams; merging would compound the drift).

For every other subcommand (gh pr list, gh issue create, gh release, …) the shim execs the real binary unchanged. No process overhead, no output rewriting.

Install

tools/gh-auth-status-shim/install.sh

Default target: $HOME/.local/bin/gh. Override with --target /path/to/dir.

The installer:

  • Verifies the target directory is on your PATH AHEAD of the real gh.
  • If PATH ordering isn't correct, prints the export line you need to add to your shell rc.
  • Backs up an existing shim to <target>.bak.<timestamp> before overwriting (different content only — same content is a no-op).
  • Refuses to overwrite a non-shim file at the target.
  • Does not modify your shell rc files.

After install:

which gh   # should show ~/.local/bin/gh
gh --version  # passes through to real gh; should show real gh version

To activate inside CC Desktop on Linux, you typically need no further action — CC Desktop inherits the user's PATH at launch. On macOS, see the limitations below.

Uninstall

tools/gh-auth-status-shim/uninstall.sh

Default target: $HOME/.local/bin/gh. Override with --target /path/to/dir.

The uninstaller:

  • Removes the shim at the target.
  • Removes any <target>.bak.* shim backups created by prior installs (verifies each is a shim before removing).
  • No restore-from-backup step. Every .bak.* file is by construction an older shim (install refuses to overwrite non-shim files), so restoring would silently reinstate an outdated shim.
  • Idempotent — running twice is benign.
  • Reports the export line you can remove from your shell rc.

Limitations

These are intentional design choices, not bugs.

Behavioral-change disclosure

The shim rewrites gh auth status exit-code semantics for every caller in the shim's PATH scope. That includes:

  • CC Desktop's PR poller (the intended audience).
  • Your shell prompt's auth status check, if you have one.
  • CI scripts that gate on gh auth status exit code.
  • Other tools that consume gh auth status for security-relevant decisions.

In all those cases, a transient gh failure (timeout, network hiccup) returns exit 0 from the shim. The worst case is a slightly-delayed surfacing of a real auth failure — not a silent loss — because every other gh subcommand (the ones that actually need auth, like gh pr list) still gets the real outcome from the real gh.

If you don't want the shim affecting non-CC callers, install it at a target dir that's only on CC Desktop's PATH and not your shell PATH.

macOS

GUI applications launched from Finder/Dock on macOS inherit launchd's PATH (/usr/bin:/bin:/usr/sbin:/sbin), NOT your shell PATH. A shim installed in ~/.local/bin is invisible to CC Desktop on macOS unless:

  • You install the shim at a path inside launchd's default PATH (requires sudo and arguably worse than the false toast), OR
  • You modify launchd's PATH globally via launchctl config user path … (system-wide, affects every GUI app).

The install.sh PATH-ordering check inspects your shell PATH, which can give macOS users false confidence. The shim still installs and the which gh check passes; it just doesn't affect CC Desktop's gh resolution.

macOS coverage is currently unverified. If you're on macOS and willing to validate, please post results to CC#67055.

Native Windows CC Desktop

Native Windows CC Desktop spawns gh.exe through Windows PATH resolution. A bash shim on a WSL or Git-Bash PATH is invisible to that spawn.

  • Windows users running CC inside WSL (CC Desktop also inside WSL): covered, but an unusual configuration.
  • Windows users running native CC Desktop: NOT covered. Wait for Anthropic's classifier fix or for a future PowerShell port (not in this repo's scope).

gh auth status --json not used

gh supports --json hosts for structured output. The shim uses text matching because:

  1. The --json hosts output is intended for hostname queries and its state field semantics for the specific failure cases the shim has to classify (timeout, transient network, Keychain anonymous-fallback HTTP 401) are not documented and may not be present on the stderr-stream-only failure paths.
  2. gh's text output has been stable across recent versions on the specific strings the classifier anchors on ("Logged in to github.com", "not logged in", "HTTP 401").
  3. The conservative-default posture (ambiguous → propagate) means classifier drift produces "slightly delayed surfacing of a real failure," not a security regression.

If a future Codex review or sim run surfaces a structural-output failure path the regex misses, the classifier can be rewritten to use --json.

Classification table is validated against a specific gh range

The classifier strings are anchored on gh's output as of the version range below. gh's output has historically reworded across releases — when that happens, the table needs refresh.

Validated against: gh v2.40.0 through v2.50.0 (sampling). If you observe a gh version producing strings the classifier doesn't match, please open an issue or PR with the captured text.

Debug logging

Set GH_AUTH_STATUS_SHIM_DEBUG_LOG=/path/to/file to capture per-invocation logs:

[gh-auth-status-shim 2026-06-12T19:58:25Z] auth status: invoking real gh at /usr/bin/gh (timeout 4s)
[gh-auth-status-shim 2026-06-12T19:58:26Z] auth status: real gh exit=0 stdout_len=58 stderr_len=0
[gh-auth-status-shim 2026-06-12T19:58:26Z] auth status: classified exit=0 (real_exit=0)

The log is append-only, never rotated by the shim. Useful for diagnosing whether CC Desktop is actually resolving gh through the shim and what classifier verdict each call received.

Internal timeout tuning

The shim's internal timeout is 4s by default. Override with GH_AUTH_STATUS_SHIM_TIMEOUT=N (in seconds, integer).

  • Don't set it above 4s unless you have a reason. CC Desktop's spawn-abandonment window is 5s; a shim that doesn't return by then is irrelevant.
  • Don't set it below 2s unless you've measured your local gh auth status latency. Tightening below normal latency creates false-transient classifications that suppress real expiry signals if the real gh itself is in a slow path.

Sunset plan

When CC#67055 closes with an Anthropic fix:

  1. CC Desktop version X ships the classifier fix.
  2. This README updates to "no longer needed if you're on CC version ≥ X."
  3. The tool is not deleted from this repo (preserves the install path for users on older CC versions).
  4. A future cache-fix release deprecates the tool with a removal date 6 months out.

Track the issue status: anthropics/claude-code#67055. When it closes, run uninstall.sh and remove the export PATH=… line you added.

Coverage scope

Platform CC Desktop launch path Shim covered?
Linux desktop, CC Desktop launched from shell shell PATH inherited Yes
Linux desktop, CC Desktop launched from .desktop file Desktop Entry's PATH (often shell PATH) Yes if shell PATH inherits — varies by desktop environment
macOS, CC Desktop launched from Finder/Dock launchd PATH Not by default — see macOS limitations
macOS, CC Desktop launched from terminal shell PATH inherited Yes
Windows native, CC Desktop launched from Start Menu Windows PATH (separate from WSL) No — bash shim invisible
Windows inside WSL, CC Desktop also inside WSL WSL shell PATH Yes (unusual config)

Per-feeder-path coverage

CC#67055 feeder path Shim coverage
Slow gh exceeding CC's 5s (Keychain slow-read, event-loop stalls) Covered — shim's 4s internal timeout returns exit 0 before CC's 5s abandonment.
Network transient (timeout, connection refused, resolve failure) Covered — classifier matches stderr signals and returns 0.
Anonymous-401 from gh's silent Keychain fallback (cli/cli#13317) NOT suppressed — propagated as expiry by the conservative classifier. HTTP 401 is indistinguishable from a real expired token at the wire level; suppressing it would hide genuine expiry. The user's workflow path here is to re-auth (gh auth login). If a future Codex review surfaces a more specific signal that distinguishes the anonymous-fallback case from a real 401, the classifier can suppress that narrower case in v2.
Deleted-cwd spawn failure (CC#67055 issue update feeder #4) NOT covered — spawn fails before any gh (real or shim) executes.
Genuinely expired token Correctly propagates — classifier matches "not logged in" and returns the real exit code, letting CC's toast fire as intended.

Troubleshooting

Q: which gh shows the shim but CC Desktop still produces the toast. A: On macOS, see the launchd PATH note above. On Linux, check that CC Desktop was launched from a context that inherits your shell PATH; relaunch from ~/.config/autostart/ or from a shell that has the export line.

Q: My non-CC gh auth status checks broke after install. A: Expected — see the behavioral-change disclosure. Install at a target dir that's only on CC Desktop's PATH if you need to preserve your shell's gh auth status semantics.

Q: The shim isn't honoring my --hostname flag. A: Report this as a bug. The shim should pass all flags through to the real gh.

Q: How do I know what classification verdict the shim made for a given call? A: Set GH_AUTH_STATUS_SHIM_DEBUG_LOG=/path/to/log and inspect the log after the call.

Q: I'm on gh version X and the classifier isn't matching the output I'm seeing. A: gh's text output has historically reworded across releases. Capture the failing output and open an issue. As a workaround, set GH_AUTH_STATUS_SHIM_DEBUG_LOG= to confirm the classifier sees the unrecognized text, and the conservative default will propagate the real exit code (which means worst case is one false toast — your behavior before the shim).

Contributing

See lib/classify-auth-status.sh for the classification table. Adding a new failure-mode classification:

  1. Add a regex to _GHASS_*_RE at the top of the helper.
  2. Add a case to classify_auth_status_output_text.
  3. Add a case to classify_auth_status_exit_code (suppress vs propagate).
  4. Add a bats unit test covering the new classification.

CI runs bats tools/gh-auth-status-shim/tests/ on Linux + macOS, with the macOS run explicitly invoking the bats suite under /bin/bash (3.2) to verify the bash 3.2 floor. shellcheck runs in CI default mode (not -s sh, which enforces POSIX sh and would reject legal bash 3.2 constructs).

License

Same as the parent repo (MIT).