How to Configure GitHub Personal Access Tokens for Agent-Reach

Agent-Reach authenticates GitHub API requests using a personal access token stored under the github_token configuration key, which you can set via the CLI command python -m agent_reach.cli config set github-token <token> or by manually editing the YAML configuration file.

To enable authenticated access to the GitHub API and avoid strict rate limits, you must configure GitHub personal access tokens for Agent-Reach before executing commands that fetch repository data. The tool persists this credential in a local YAML configuration file managed by the Config class in agent_reach/config.py, while the CLI interface defined in agent_reach/cli.py provides convenient commands to update these settings securely.

Why Agent-Reach Requires a GitHub Token

When Agent-Reach queries the GitHub API, it must provide an Authorization header containing Bearer <token>. Without a valid token, GitHub’s unauthenticated rate limits are extremely low (60 requests per hour), and many endpoints return "unauthenticated" errors. According to the source code in agent_reach/cli.py, the helper function _github_get_with_retry (implemented around line 1645) retrieves the token using config.get("github_token") and injects it into the request headers to ensure reliable API access.

Method 1: Configure via the CLI Command

The recommended approach uses the built-in configuration command to write the token directly to the settings file. This method invokes config.set("github_token", value) in agent_reach/config.py (around line 29) to persist the value securely.

Run the following command, replacing the placeholder with your actual token:

python -m agent_reach.cli config set github-token ghp_YourGeneratedTokenHere

Note that the CLI argument uses a hyphen (github-token), which maps to the internal configuration key github_token with an underscore. This command stores the token in the user configuration directory, typically located at ~/.config/agent-reach/config.yaml.

Method 2: Manual Configuration File Editing

Alternatively, you can edit the configuration file directly using a text editor. Create or modify the file at ~/.config/agent-reach/config.yaml and add the following entry:

github_token: ghp_YourGeneratedTokenHere

Ensure the file uses valid YAML syntax with no indentation errors. The Config class loads this key automatically on the next CLI invocation or when imported programmatically.

Verifying Your Token Configuration

Confirm the token is stored correctly by retrieving it from the command line:

python -m agent_reach.cli config get github-token

To access the token programmatically in Python scripts, import the config module and call the getter method:

from agent_reach import config

# Retrieve the stored token

github_token = config.get("github_token")

# Example: Make an authenticated request

import requests
headers = {"Authorization": f"Bearer {github_token}"}
resp = requests.get("https://api.github.com/user", headers=headers)
print(resp.json())

Security Best Practices

Protect your personal access token to prevent unauthorized access to your GitHub account. Follow these guidelines when configuring Agent-Reach:

• Restrict file permissions: Set the configuration file to user-read-only using chmod 600 ~/.config/agent-reach/config.yaml on Unix-based systems.
• Never commit tokens: Ensure the config file path is included in .gitignore if your working directory includes the Agent-Reach configuration folder.
• No logging exposure: The Agent-Reach CLI never logs or prints the full token value to stdout, but verify that your terminal history does not capture the raw command containing the token.

Summary

• Configuration key: Agent-Reach references GitHub tokens using the github_token key defined in agent_reach/config.py.
• CLI setup: Use python -m agent_reach.cli config set github-token <token> to write credentials via the command line.
• Manual setup: Edit ~/.config/agent-reach/config.yaml directly to add github_token: <value>.
• Implementation: The token is injected into API requests by _github_get_with_retry in agent_reach/cli.py (line ~1645) as a Bearer authorization header.
• Security: Store the configuration file with restricted permissions (600) and avoid exposing tokens in shell history.

Frequently Asked Questions

Where does Agent-Reach store the GitHub token?

Agent-Reach stores the token in a YAML configuration file located at ~/.config/agent-reach/config.yaml (or the platform-equivalent user config directory). The Config class in agent_reach/config.py handles reading and writing to this location using the key github_token.

Why does Agent-Reach need a personal access token?

Without an authenticated token, GitHub applies severe rate limiting to API requests. The token allows Agent-Reach to access higher rate limits and private repository data by providing an Authorization header (Bearer <token>) in every request, as implemented in the _github_get_with_retry function within agent_reach/cli.py.

Can I use the token programmatically without the CLI?

Yes. You can import the configuration module directly in Python scripts and retrieve the token using config.get("github_token"). This allows custom scripts built on top of Agent-Reach to access the stored credential without invoking the CLI subprocess, leveraging the same configuration file used by the command-line interface.

Is my GitHub token exposed in CLI output or logs?

No. According to the source implementation in agent_reach/cli.py, the token value is never printed to standard output or written to log files. However, be aware that your shell history may record the token if you type it directly into the config set command; consider using environment variable substitution or secure input methods for sensitive tokens.

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