How to Configure GitHub Personal Access Tokens for Private Repository Access in Agent Reach

To configure GitHub personal access tokens for private repository access in Agent Reach, use the CLI command agent-reach configure github-token <TOKEN> to store the token in ~/.agent-reach/config.yaml, which the GitHubChannel class reads via Config.get("github_token").

The open-source Agent Reach project (Panniantong/Agent-Reach) authenticates to private GitHub repositories using personal access tokens managed through a central configuration system. This guide explains how to configure GitHub personal access tokens for private repository access in Agent Reach using the built-in Config class and CLI tools.

Understanding the Configuration Architecture

Agent Reach stores user-specific settings in a YAML file located at ~/.agent-reach/config.yaml. The central configuration logic resides in agent_reach/config.py, where the Config class handles persistence and retrieval. When you configure a GitHub token, the system writes to the github_token key using the Config.set method (lines 27-33), which atomically saves the value to disk with secure permissions.

Step-by-Step Configuration Guide

Generate a GitHub Personal Access Token

Visit https://github.com/settings/tokens to create a new token. You do not need any special scopes for Agent Reach; the default "no scope" token works for reading private repositories. Copy the generated token immediately, as GitHub displays it only once.

Store the Token via CLI

The recommended method uses the configure sub-command. The CLI parser in agent_reach/cli.py (lines 1101-1103) handles the github-token argument and invokes config.set("github_token", value):

agent-reach configure github-token <YOUR_TOKEN>

The CLI confirms with "✅ GitHub token configured!" and persists the value to ~/.agent-reach/config.yaml.

Verify File Creation

The Config.save method (lines 49-66) creates the configuration directory and file with 0600 permissions (read/write for owner only). Verify the token exists:

cat ~/.agent-reach/config.yaml

Expected output:

github_token: ghp_your_token_here

How Agent Reach Retrieves the Token

The Config.get method (lines 69-77) implements a fallback chain: it first checks the in-memory configuration dictionary, then falls back to the GITHUB_TOKEN environment variable (uppercase). This allows flexibility between persistent configuration and temporary environment-based authentication.

The GitHubChannel class in agent_reach/channels/github.py uses this token to authenticate API requests. The GitHubChannel.check method (lines 19-43) performs health checks to verify the token works with either the authenticated gh CLI or direct API calls.

Alternative Configuration Methods

Environment Variable Override

Set the token temporarily without writing to disk:

export GITHUB_TOKEN=ghp_your_token_here

This takes precedence over the configuration file when using Config.get("github_token").

Manual Configuration File Editing

Advanced users can edit ~/.agent-reach/config.yaml directly:

github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

Verification and Troubleshooting

Run the diagnostic command to verify your setup:

agent-reach doctor

This executes GitHubChannel.check and reports whether the token is valid. If the gh CLI is missing, the check may warn but still report success if the token is valid for API calls.

Summary

• Agent Reach stores GitHub tokens in ~/.agent-reach/config.yaml under the github_token key.
• Use agent-reach configure github-token <TOKEN> to write the configuration via Config.set in agent_reach/config.py.
• The system creates the config file with 0600 permissions for security.
• Config.get checks the in-memory dict first, then falls back to the GITHUB_TOKEN environment variable.
• Verify authentication works using agent-reach doctor, which invokes GitHubChannel.check in agent_reach/channels/github.py.

Frequently Asked Questions

Where does Agent Reach store my GitHub token?

Agent Reach writes the token to ~/.agent-reach/config.yaml under the github_token key. The Config.save method in agent_reach/config.py sets file permissions to 0600, ensuring only your user account can read or write the file.

Can I use an environment variable instead of the config file?

Yes. The Config.get method checks for GITHUB_TOKEN (uppercase) as a fallback after checking the in-memory configuration. This is useful for CI/CD pipelines or temporary sessions where you don't want to persist credentials to disk.

What permissions does my GitHub token need?

You do not need any special scopes for Agent Reach. The default "no scope" personal access token provides sufficient permissions to read private repositories. Generate yours at https://github.com/settings/tokens.

How do I verify my token is working correctly?

Run agent-reach doctor to execute the health check. The GitHubChannel.check method in agent_reach/channels/github.py (lines 19-43) validates the token by attempting authenticated API calls, reporting ok if successful.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}