# Local Development

## Prerequisites

- Go 1.23 or later
- A GitHub personal access token (PAT)

## Getting a GitHub Token

1. Go to [https://github.com/settings/tokens](https://github.com/settings/tokens)
2. Click "Generate new token" → "Generate new token (classic)"
3. Give it a name (e.g., "awesome-coding-agents")
4. Select scope: **`public_repo`** (needed to read public repo metadata)
5. Click "Generate token" and copy the value

The updater reads public repos only; `public_repo` scope is sufficient and safe.

## Running Locally

```bash
export GITHUB_TOKEN=ghp_your_token_here
go run .
```

The tool will:
- Read `data/agents.yml`
- Fetch live metadata from GitHub GraphQL API
- Append star counts to `data/history.jsonl`
- Regenerate `README.md` from `templates/readme.tmpl`

## Reverting Local Changes

Before opening a PR, undo local modifications:

```bash
git restore data/history.jsonl README.md
```

This removes the snapshot files generated by your local run, leaving only your edits to `data/agents.yml`.

## Rate Limits

- **With GITHUB_TOKEN:** 5,000 requests/hour
- **Without token:** 60 requests/hour

Always set `GITHUB_TOKEN` when testing locally to avoid hitting the unauthenticated limit.

## Next Steps

To add agents, see [CONTRIBUTING.md](./CONTRIBUTING.md).