How to Configure a GitHub Personal Access Token for Private Repositories in Agent Reach

Agent Reach stores GitHub Personal Access Tokens in ~/.agent-reach/config.yaml under the github_token key, which you can set via the CLI using agent-reach configure github-token <TOKEN> to enable authenticated access to private repositories.

To work with private GitHub repositories, Agent Reach requires a Personal Access Token (PAT) for authentication. According to the Panniantong/Agent-Reach source code, the tool handles token storage, retrieval, and validation through a centralized configuration system that supports both file-based and environment variable configurations.

Where Agent Reach Stores the GitHub Token

Agent Reach maintains user-specific settings in a YAML file located at ~/.agent-reach/config.yaml. The github_token key holds the value used to authenticate with the GitHub API.

In agent_reach/config.py, the Config.set method (lines 27-33) handles writing values to this configuration file. When you save a token, the Config.save method (lines 49-66) persists the data to disk with permissions 0600 (read/write for the owner only), ensuring the token remains private from other system users.

Configuring the Token via CLI

1. Generate a Personal Access Token on GitHub

Navigate to https://github.com/settings/tokens and generate a new token. Agent Reach does not require any special scopes—the default "no scope" token provides sufficient permissions for reading private repositories. Copy the generated token immediately, as GitHub displays it only once.

2. Store the Token Using the Configure Command

Run the following command to securely save your token:

agent-reach configure github-token <YOUR_TOKEN>

The CLI code in agent_reach/cli.py (lines 1101-1103) parses the github-token argument and invokes config.set("github_token", value) to persist the entry. Upon success, the CLI prints "✅ GitHub token configured!" confirming the operation.

3. Verify the Configuration File (Optional)

Confirm the token was written correctly by inspecting the configuration file:

cat ~/.agent-reach/config.yaml

You should see the entry:

github_token: ghp_xxxxxxxxxxxxxxxxxxxx

4. Validate the Connection

Run the health check to verify the token works:

agent-reach doctor

This invokes GitHubChannel.check in agent_reach/channels/github.py (lines 19-43), which validates the token against the GitHub API. Valid configurations report ok; missing gh CLI installations may report warn but the token remains functional for direct API calls.

How the Token is Loaded at Runtime

Agent Reach retrieves the token using the Config.get method in agent_reach/config.py (lines 69-77). The system checks values in the following priority order:

1. In-memory configuration dictionary
2. Environment variable GITHUB_TOKEN (uppercase)
3. Configuration file (~/.agent-reach/config.yaml)

This hierarchy allows temporary overrides via environment variables without modifying the config file. The GitHubChannel class uses this retrieved token to authenticate API requests or invoke the gh CLI when available.

Manual Configuration (Advanced)

You can directly edit the configuration file instead of using the CLI:

# ~/.agent-reach/config.yaml

github_token: ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ123456

Ensure the file maintains 0600 permissions after editing to prevent unauthorized access.

Programmatic Access

For custom scripts or extensions, access the token programmatically through the Config class:

from agent_reach.config import Config

cfg = Config()
token = cfg.get("github_token")  # Returns string or None

# Masked output for safety

if token:
    print("GitHub token:", token[:8] + "...")

Summary

• Agent Reach stores tokens in ~/.agent-reach/config.yaml under the github_token key
• Use agent-reach configure github-token <TOKEN> to set values via CLI (implemented in agent_reach/cli.py, lines 1101-1103)
• Configuration files use 0600 permissions to restrict access to the owner only
• The Config.get method checks the in-memory cache, then GITHUB_TOKEN environment variable, then the config file (lines 69-77 in agent_reach/config.py)
• No special GitHub scopes are required for private repository access
• Verify setup using agent-reach doctor, which triggers GitHubChannel.check

Frequently Asked Questions

Do I need specific scopes for the GitHub Personal Access Token?

No. According to the Agent Reach implementation, the default "no scope" token works for reading private repositories. You do not need to assign repo or other scopes unless you plan to perform write operations beyond the tool's standard read/search functionality.

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

Yes. The Config.get method (lines 69-77 in agent_reach/config.py) falls back to the GITHUB_TOKEN environment variable if the key is not set in the configuration file or in-memory cache. Set export GITHUB_TOKEN=ghp_... in your shell to override the config file temporarily.

Where is the Agent Reach configuration file stored?

The configuration file is located at ~/.agent-reach/config.yaml on Unix-like systems. The Config.save method creates this file with 0600 permissions (readable only by the owner) to protect sensitive tokens stored within.

How do I verify my GitHub token is configured correctly?

Run agent-reach doctor to execute the health check logic in agent_reach/channels/github.py (lines 19-43). This validates that the token can authenticate with the GitHub API. If the gh CLI is installed, it also verifies CLI integration. A valid token produces an ok status in the GitHub section of the output.

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