Configure GitHub Personal Access Token for Agent Reach Private Repositories

To enable Agent Reach to access private GitHub repositories, run agent-reach configure github-token <YOUR_TOKEN> which stores the credential in ~/.agent-reach/config.yaml under the github_token key.

Agent Reach requires authentication to interact with private GitHub repositories. According to the Panniantong/Agent-Reach source code, the tool manages sensitive credentials through a local YAML configuration file and provides a dedicated CLI command to handle the GitHub personal access token securely.

Where Agent Reach Stores GitHub Credentials

User-specific settings reside in ~/.agent-reach/config.yaml. The github_token key stores the GitHub personal access token used for all private repository operations.

In agent_reach/config.py, the Config class handles persistence. The Config.set method (lines 27-33) writes values to an in-memory dictionary, while Config.save (lines 49-66) flushes data to disk with 0600 permissions (read/write for owner only).

Step-by-Step Configuration Guide

Generate a GitHub Personal Access Token

Navigate to https://github.com/settings/tokens. Create a new token with a descriptive name.

Agent Reach does not require any special scopes for reading private repositories; a token with default settings (no scopes selected) works for basic read operations. Copy the generated token immediately, as GitHub displays it only once.

Store the Token Using the CLI

The recommended method uses the configure sub-command. In agent_reach/cli.py (lines 1101-1103), the CLI parses the github-token argument and calls config.set("github_token", value) internally.

agent-reach configure github-token ghp_abcdefghijklmnopqrstuvwxyz1234

The CLI confirms successful storage with the message "✅ GitHub token configured!"

Verify the Configuration

Check the configuration file directly:

cat ~/.agent-reach/config.yaml

You should see the token stored under the github_token key:

github_token: ghp_abcdefghijklmnopqrstuvwxyz1234

Run the health check to validate the token works:

agent-reach doctor

The GitHub section should report ok if the token is valid and the gh CLI is installed.

How the Token Is Used Internally

When components need API access, they invoke Config.get("github_token") from agent_reach/config.py (lines 69-77). This method first checks the in-memory dictionary, then falls back to the GITHUB_TOKEN environment variable if the config file value is absent.

The GitHubChannel class in agent_reach/channels/github.py (lines 19-43) uses this token to authenticate via the gh CLI or direct API calls during health checks and repository operations.

Alternative Configuration Methods

Direct File Editing

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

github_token: ghp_YourActualTokenHere

Ensure the file maintains 0600 permissions (readable only by the owner).

Environment Variable Override

Set GITHUB_TOKEN in your shell to override the config file:

export GITHUB_TOKEN=ghp_YourActualTokenHere
agent-reach doctor

Programmatic Access

For custom integrations, access the token via Python:

from agent_reach.config import Config

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

print("Token prefix:", token[:8] + "...")  # Masked for safety

Summary

• Agent Reach stores GitHub tokens in ~/.agent-reach/config.yaml under the github_token key with restricted 0600 permissions
• Use agent-reach configure github-token <TOKEN> to set credentials securely via the CLI
• The Config class in agent_reach/config.py handles storage while Config.get supports environment variable fallback
• The GitHubChannel class in agent_reach/channels/github.py consumes the token for API authentication
• Verify setup with agent-reach doctor to ensure private repository access works correctly

Frequently Asked Questions

Do I need specific GitHub scopes for the token?

No. Agent Reach requires no special scopes for basic private repository access. A token generated with default settings (no scopes selected) works for read operations, as the tool primarily needs to read repository contents and metadata.

Can I use an existing GitHub token?

Yes. Any valid GitHub personal access token can be configured using the agent-reach configure github-token command or by setting the GITHUB_TOKEN environment variable. The system accepts standard ghp_ tokens without validation of specific scopes.

Where does Agent Reach check if my token is working?

The GitHubChannel.check method in agent_reach/channels/github.py (lines 19-43) validates the token during the agent-reach doctor command. This health check verifies authentication via the gh CLI when available, or validates API accessibility through direct token usage.

Is the token stored securely?

Yes. The Config.save method in agent_reach/config.py (lines 49-66) explicitly sets file permissions to 0600 (readable and writable only by the owner). The configuration file resides in your home directory under .agent-reach/, keeping the token isolated from other users on the system.

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