claude-code - 💡(How to fix) Fix [DOCS] Bash tool docs missing `gh` GitHub API rate-limit hint behavior

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/tools-reference

Section/Topic

Bash tool behavior, plus related gh guidance for GitHub operations

Current Documentation

The Bash tool reference currently says:

Bash tool behavior

The Bash tool runs each command in a separate process with the following persistence behavior:

• When Claude runs cd in the main session, the new working directory carries over to later Bash commands as long as it stays inside the project directory or an additional working directory you added with --add-dir, /add-dir, or additionalDirectories in settings.
• Environment variables do not persist. An export in one command will not be available in the next.

The best-practices guide currently says:

CLI tools are the most context-efficient way to interact with external services. If you use GitHub, install the gh CLI. Claude knows how to use it for creating issues, opening pull requests, and reading comments. Without gh, Claude can still use the GitHub API, but unauthenticated requests often hit rate limits.

No current page explains the new Bash tool hint shown when a gh command itself hits GitHub's API rate limit.

What's Wrong or Missing?

Changelog v2.1.116 added this behavior:

Bash tool now surfaces a hint when gh commands hit GitHub's API rate limit, so agents can back off instead of retrying.

The current docs tell users to install and use gh, and they document generic Bash tool persistence behavior, but they do not document:

• that Claude Code detects gh rate-limit failures specially
• that the Bash tool now surfaces a hint for this case
• that the hint is meant to stop repeated retries and encourage backoff/re-authentication instead
• what users should do next when they hit this condition

Suggested Improvement

Add a short note under Bash tool behavior describing this error-handling behavior for GitHub CLI commands.

Suggested content outline:

1. Explain that when a gh command hits GitHub's API rate limit, Claude Code surfaces a Bash-tool hint instead of leaving the agent to keep retrying blindly.
2. State that the hint means the agent should back off, wait for reset, or use authenticated GitHub CLI access if the command was unauthenticated.
3. Cross-reference the existing gh guidance in best-practices and any authentication/setup guidance that already tells users to configure gh or GH_TOKEN.
4. Optionally include a short example of the kind of hint/result users might see so they can recognize the condition quickly.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Source: Changelog v2.1.116

Exact changelog entry: Bash tool now surfaces a hint when gh commands hit GitHub's API rate limit, so agents can back off instead of retrying