Solving Claude Code's gh Command Permission Prompts with a Readonly Wrapper

Current Situation Analysis

When integrating the GitHub CLI (gh) into Claude Code workflows, developers encounter a critical friction point: Claude Code triggers an interactive permission prompt for every single gh api invocation, regardless of the operation's intent. Even harmless, read-only queries like listing repository commits require manual approval, effectively breaking autonomous agent execution.

The fundamental failure mode stems from Claude Code's permission model, which operates at the command-execution level rather than the semantic operation level. The system cannot natively distinguish between a safe read operation (gh api "repos/.../commits") and a destructive write operation (gh pr merge or gh repo delete).

Traditional workarounds fail because:

• Blanket Allow: Granting unrestricted allow for gh eliminates prompts but exposes the repository to unintended modifications, secret leaks, or accidental destructive actions by the AI agent.
• Command Filtering: Regex-based shell aliases or PATH manipulation are easily bypassed by LLMs that generate commands dynamically or fall back to alternative invocation methods.
• Credential Sharing: Using the same gh authentication state for both read and write contexts makes it impossible to enforce least-privilege principles at the agent level.

WOW Moment: Key Findings

By decoupling read and write contexts using environment-based configuration isolation, we achieve a secure, frictionless workflow. The following comparison demonstrates the operational impact of the ghro wrapper approach versus standard configurations:

Approach	Permission Prompt Frequency	Security Risk (Write Exposure)	Workflow Autonomy
Default gh (Manual Prompts)	100%	Low (Human-in-the-loop)	0%
Default gh (Blanket Allow)	0%	Critical	100%
ghro Readonly Wrapper	0% (Read) / 100% (Write)	Minimal	95%+

Key Findings:

• Sweet Spot: The GH_CONFIG_DIR environment variable enables complete credential and configuration isolation without modifying the gh binary or relying on fragile shell parsing.
• Zero-Trust Read Path: Read operations execute autonomously while write operations remain gated, preserving both developer velocity and repository integrity.
• Agent-Native Design: The solution aligns with Claude Code's instruction-following architecture by explicitly routing operations through semantic command separation (ghro vs gh).

Core Solution

The implementation relies on GitHub's Fine-grained Personal Access Tokens, environment-driven configuration isolation, and a lightweight shell wrapper. Follow these steps to deploy the readonly execution path:

1. Create a Fine-grained Personal Access Token Generate a token on GitHub with strictly read-only repository scopes. Ensure write permissions for contents, pull requests, issues, and secrets are explicitly disabled.

2. Authenticate with an Isolated Readonly Profile Leverage GH_CONFIG_DIR to maintain separate credentials from your default gh configuration. This prevents credential leakage and enforces scope boundaries.

GH_CONFIG_DIR=~/.config/ghro gh auth login --with-token <<< "<your-token>"

3. Create the ghro Wrapper Script Place the following script in a directory included in your system PATH. The exec directive ensures process replacement, maintaining proper signal handling and avoiding zombie processes.

#!/bin/sh
GH_CONFIG_DIR=~/.config/ghro exec gh "$@"

Make the wrapper executable:

chmod +x ghro

4. Configure Claude Code Instructions Update your project's CLAUDE.md to explicitly route operations. This directive ensures the model respects the read/write boundary during autonomous execution.

## When fetching information or content from GitHub
- Use the ghro command for readonly access to GitHub information
- Fetch cannot retrieve file contents — use the ghro command instead
- For any write operations, use the gh command instead of ghro

With this architecture, read operations bypass permission prompts entirely, while write operations correctly trigger Claude Code's safety gates. The separation of concerns provides both guardrails and operational convenience.

Pitfall Guide

1. Over-Permissive Fine-grained Token Scopes: Accidentally granting "Read and Write" or "Admin" scopes to the readonly token defeats the entire security model. Always verify repository access is strictly limited to Contents: Read-only, Issues: Read-only, and Pull Requests: Read-only.
2. GH_CONFIG_DIR Path Resolution Failures: Using unexpanded ~ or relative paths in non-interactive shells can cause exec gh to fallback to the default config or fail silently. Ensure the wrapper uses absolute paths or that the execution environment properly expands tilde notation.
3. Claude Code Context Drift: LLMs may ignore implicit instructions over time. If CLAUDE.md lacks explicit routing rules, the model may default to gh for all operations. Use imperative, rule-based syntax and periodically audit agent command logs.
4. Bypassing via Direct HTTP Clients: Claude Code might attempt to use curl or wget with environment variables or hardcoded tokens if ghro is restricted. Ensure no global GITHUB_TOKEN is exposed to the agent's execution environment, and rely solely on the isolated ghro profile.
5. Shell Compatibility & exec Omission: Replacing exec with a standard subshell call (GH_CONFIG_DIR=... gh "$@") creates a child process that breaks signal propagation (e.g., Ctrl+C won't terminate the CLI properly). Always use exec to replace the shell process.
6. Write Operation Prompt Fatigue: While ghro solves read friction, write operations will still prompt. Define clear thresholds in CLAUDE.md for when to use gh vs ghro to prevent unnecessary interruptions or silent failures when write access is genuinely required.

Deliverables

• Architecture Blueprint: Visual workflow diagram showing the read/write command routing, GH_CONFIG_DIR isolation boundaries, and Claude Code permission gate interactions.
• Implementation Checklist: Step-by-step verification guide covering token scope validation, PATH configuration, wrapper execution testing, and CLAUDE.md directive validation.
• Configuration Templates:
  • Ready-to-deploy ghro wrapper script with error handling and absolute path fallbacks
  • CLAUDE.md routing ruleset optimized for Claude Code's instruction parsing
  • Fine-grained PAT scope matrix template for GitHub organization/enterprise deployment