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

Agent Reach stores GitHub authentication credentials in ~/.agent-reach/config.yaml under the github_token key, which you can set via the agent-reach configure github-token <TOKEN> command or the GITHUB_TOKEN environment variable.

Agent Reach requires a GitHub personal access token to clone and analyze code from private repositories. According to the Panniantong/Agent-Reach source code, the tool centralizes all user credentials in a YAML configuration file and exposes a simple CLI interface for secure token management.

Where Credentials Are Stored

The configuration system is implemented in agent_reach/config.py. All user-specific settings persist to ~/.agent-reach/config.yaml with restrictive file permissions (0600). The specific key for GitHub authentication is github_token.

When the CLI receives the configure subcommand, it calls Config.set("github_token", value) (lines 27-33 in agent_reach/config.py), which writes the value to disk through the Config.save method (lines 49-66). This ensures your token is readable only by your user account.

Step-by-Step Configuration

1. Generate a GitHub Personal Access Token

Navigate to https://github.com/settings/tokens and create a new token. Agent Reach only requires read access to private repositories, so you can create a token with no scopes selected. Copy the generated token immediately—it displays only once.

2. Configure Agent Reach via CLI

The recommended method uses the configure subcommand implemented in agent_reach/cli.py (lines 1101-1103):

agent-reach configure github-token ghp_YourTokenHere

The CLI maps the argument github-token to the internal key github_token and persists it via Config.set. After execution, the terminal prints "✅ GitHub token configured!" confirming the entry was saved.

3. Verify the Configuration

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

agent-reach doctor

The GitHubChannel.check method in agent_reach/channels/github.py (lines 19-43) validates the token against the GitHub API. If the token is valid and the gh CLI is installed, the check reports ok.

Alternative Configuration Methods

Environment Variable Override

The Config.get method in agent_reach/config.py (lines 69-77) implements a fallback mechanism. If github_token is not set in the YAML file, Agent Reach checks for the GITHUB_TOKEN environment variable (uppercase):

export GITHUB_TOKEN=ghp_YourTokenHere

This is useful for CI/CD pipelines where writing to the filesystem is not permitted.

Manual File Editing

Advanced users can edit the configuration file directly:

# ~/.agent-reach/config.yaml

github_token: ghp_YourGeneratedTokenString

The file must remain readable only by the owner (permissions 0600), which the Config.save method enforces automatically.

Programmatic Token Access

To read the configured token programmatically in Python:

from agent_reach.config import Config

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

# Masked output for logging

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

The Config.get method first checks the in-memory dictionary, then falls back to the environment variable, ensuring flexibility across deployment environments.

Summary

• Storage location: Agent Reach stores tokens in ~/.agent-reach/config.yaml under the github_token key with 0600 permissions.
• CLI command: Use agent-reach configure github-token <TOKEN> to persist credentials securely.
• Environment fallback: Set GITHUB_TOKEN if you prefer environment-based configuration.
• Verification: Run agent-reach doctor to validate that GitHubChannel can authenticate using the stored token.
• Source references: Configuration logic resides in agent_reach/config.py (lines 27-33, 49-77), CLI parsing in agent_reach/cli.py (lines 1101-1103), and channel validation in agent_reach/channels/github.py (lines 19-43).

Frequently Asked Questions

Do I need special scopes for the GitHub token?

No. Agent Reach only requires read access to private repositories, which works with the default "no scope" token. You do not need to enable repo or other scopes unless you plan to perform write operations.

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

Yes. According to the Config.get implementation in agent_reach/config.py (lines 69-77), Agent Reach checks for the uppercase GITHUB_TOKEN environment variable if the github_token key is not present in the YAML configuration file.

How do I verify my token is working correctly?

Run agent-reach doctor in your terminal. This executes the GitHubChannel.check method, which validates the token against the GitHub API. A successful check returns ok in the GitHub section of the output.

Is the token stored securely on disk?

Yes. The Config.save method in agent_reach/config.py (lines 49-66) creates the configuration file with 0600 permissions (read/write for owner only), preventing other users on the system from accessing your GitHub credentials.

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