How to Configure GitHub Personal Access Tokens for Agent Reach to Access Private Repositories

Run agent-reach configure github-token <YOUR_TOKEN> to store your GitHub Personal Access Token in ~/.agent-reach/config.yaml, enabling Agent Reach to authenticate against private repositories.

Agent Reach stores authentication credentials in a local YAML configuration file and retrieves them via the Config class when interacting with the GitHub API. To access private repositories, you must provide a Personal Access Token (PAT) that the tool reads from disk or from the GITHUB_TOKEN environment variable.

Creating a GitHub Personal Access Token

Agent Reach does not require special OAuth scopes for basic repository access. Generate a token with default permissions:

1. Navigate to https://github.com/settings/tokens.
2. Click Generate new token (classic).
3. Leave all scopes unchecked—the default "no scope" token supports reading private repositories.
4. Copy the token immediately; GitHub displays it only once.

Configuring the Token via CLI

The recommended configuration method uses the built-in configure subcommand. In agent_reach/cli.py (lines 1101–1103), the CLI parses the github-token argument and invokes config.set("github_token", value):

agent-reach configure github-token ghp_xxxxxxxxxxxxxxxxxxxx

The command writes the value to ~/.agent-reach/config.yaml through the Config.set method defined in agent_reach/config.py (lines 27–33).

Understanding the Configuration File

Agent Reach persists settings in ~/.agent-reach/config.yaml. The Config.save method (lines 49–66 in agent_reach/config.py) creates this file with 0600 permissions (read/write for owner only) to protect sensitive credentials.

After configuration, the file contains:

github_token: ghp_xxxxxxxxxxxxxxxxxxxx

Environment Variable Fallback

If the configuration file does not contain a token, Config.get (lines 69–77 in agent_reach/config.py) falls back to the GITHUB_TOKEN environment variable. Set it in your shell profile:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

This takes precedence only if the YAML file lacks the github_token key.

Verifying Authentication

Run the diagnostic command to confirm the GitHub channel can authenticate:

agent-reach doctor

The GitHubChannel.check method (lines 19–43 in agent_reach/channels/github.py) validates connectivity. A valid token returns ok; missing CLI tools may return warn but the token remains usable for direct API calls.

Programmatic Access

Read the token in Python using the internal API:

from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")
print(f"Authenticated with: {token[:8]}...")

This retrieves the value from memory, falling back to the environment variable if unset.

Summary

• Storage location: ~/.agent-reach/config.yaml with restricted 0600 permissions.
• CLI command: agent-reach configure github-token <TOKEN> writes to agent_reach/config.py via Config.set.
• Config key: github_token is read by Config.get with fallback to GITHUB_TOKEN environment variable.
• Verification: agent-reach doctor uses GitHubChannel.check in agent_reach/channels/github.py to validate authentication.
• Scope requirements: No special GitHub scopes required for private repository access.

Frequently Asked Questions

Do I need specific GitHub scopes for Agent Reach?

No. According to the source implementation in Panniantong/Agent-Reach, the default "no scope" Personal Access Token is sufficient for Agent Reach to read and search private repositories. The token only needs basic authentication permissions.

Where is the GitHub token stored on disk?

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

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

Yes. The Config.get method in agent_reach/config.py (lines 69–77) checks for the GITHUB_TOKEN environment variable (uppercase) if the configuration file entry is missing. Set export GITHUB_TOKEN=ghp_... in your shell to use this fallback mechanism.

How do I verify the token is working correctly?

Run agent-reach doctor. The health check invokes GitHubChannel.check in agent_reach/channels/github.py (lines 19–43), which authenticates against the GitHub API using your stored token. Success indicates the token is valid and Agent Reach can access private repositories.

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