What the agent does
The agent reads how requests reach the handlers before it adds a middleware. In a Gin API like gothinkster/golang-gin-realworld-example-app, go.mod declares Go 1.21 with gin-gonic/gin v1.10.0, GORM v1.25.12 on the SQLite driver, golang-jwt/jwt/v5, go-playground/validator/v10 and testify, and nothing that limits requests. hello.go builds gin.Default(), turns RedirectTrailingSlash off so POST bodies survive, and mounts one /api group in three layers: users.UsersRegister (POST /api/users and /api/users/login) before any middleware, then users.AuthMiddleware(false) for the anonymous article, tag and profile reads, then users.AuthMiddleware(true) for /api/user, follows and article writes. PORT defaults to 8080 and common.Init() opens the SQLite file from DB_PATH or ./data/gorm.db.
users/middlewares.go is the model for the new code: AuthMiddleware(auto401 bool) gin.HandlerFunc reads the token from an Authorization: Token … header or an access_token query parameter, parses it with the HMAC method check, and calls AbortWithStatus(401) or lets the request through as anonymous. users/routers.go shows why login needs the tightest limit: UsersLogin answers 401 with the same Not Registered email or invalid password message for an unknown email and a wrong password, which is right, but nothing slows a client that tries thousands of passwords, and UsersRegistration has no brake either. The agent adds a common/ratelimit.go with a token-bucket limiter from golang.org/x/time/rate keyed by c.ClientIP(), kept in a map behind a mutex with idle entries evicted, taking its limits from environment variables the way PORT and DB_PATH are read, and a now function so tests can move time. On refusal it sets Retry-After and aborts with 429 and a body in the {"errors": {...}} shape that common.CommonError already gives every other error.
Mounting follows the existing layering: the strict limiter goes on the /api/users group before UsersRegister, and the general one on the router before /api, so the /api/ping route and the anonymous reads are covered too. c.ClientIP() is only as good as Gin's trusted-proxy setting, and hello.go never calls SetTrustedProxies, so behind a load balancer every request would share the balancer's address; the agent sets the trusted proxies from an environment variable and says so in the pull request rather than leaving the limit to key on one address in production.
Tests follow the files beside them. users/unit_test.go and articles/unit_test.go build their own routers in setupRouter() the same way hello.go does, use httptest.NewRecorder() with testify, open a scratch database with common.TestDBInit() in TestMain and remove it with common.TestDBFree(), and common/test_helpers.go has HeaderTokenMock for authenticated requests. The new common/ratelimit_test.go sends one request over the limit from one RemoteAddr and asserts the 429 and the Retry-After header, sends from a second address and asserts it is unaffected, and advances the injected clock to show the bucket refills; a login test in users does the same through the real handler. Then the agent runs what .github/workflows/ci.yml runs: scripts/gofmt.sh, which fails on any unformatted file, scripts/coverage.sh, which runs go test -coverprofile -covermode=atomic per package on Go 1.21, 1.22 and 1.23, golangci-lint v1.61 with the staticcheck, unused and misspell linters from .golangci.yml, and gosec.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add rate limiting to this Gin API. Read hello.go, go.mod, users/middlewares.go, users/routers.go, common/utils.go and the existing unit tests first, and keep the layering hello.go uses. Add a middleware keyed by the client address with a token bucket per client, idle entries evicted, limits read from environment variables with sensible defaults, and a clock that tests can replace. Apply a strict limit to the user registration and login routes and a general limit to everything else, answer refused requests with 429, a Retry-After header and an errors body in the same shape as the other error responses, and set Gin's trusted proxies from an environment variable so the client address is right behind a proxy. Add tests with httptest and testify in the style of the existing unit tests: over the limit from one address, a second address unaffected, refill after the window, and the login route through the real handler. Run bash scripts/gofmt.sh, bash scripts/coverage.sh, go vet ./... and golangci-lint run, as the CI workflow does. Do not change go.mod beyond the one new dependency and do not change any workflow. Open a pull request that names the limits, the environment variables and the proxy setting, and quotes the test output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request on its own branch adding common/ratelimit.go and its test, two lines in hello.go that mount the strict and general limiters, a trusted-proxies call, one new line in go.mod and go.sum for golang.org/x/time, and a README note on the new environment variables. The body names the limits per route, the variables, the proxy setting and quotes the coverage and lint output.
The session read names the repository and the pull request, and the transcript keeps every command: the gofmt check, each package's go test with coverage, go vet, golangci-lint and the first test run in which the 429 assertion failed before the middleware was mounted. The changes route lists the files with their diff.
Before merging, a reviewer checks that the limiter sits before UsersRegister and not after AuthMiddleware, that the general limit is high enough for the anonymous article list a frontend polls, that the map of buckets is evicted so memory does not grow with addresses seen, that SetTrustedProxies matches the deployment, and that the test's clock is injected rather than sleeping.
Run it on every API without a rate limit
From your own server, list the repositories the Rush GitHub App installation reaches with GET /o/{org}/github, and for each service that has no limiter send POST /o/{org}/sessions with this prompt and that repository in resources, one call each with its own request_id. Each run works in its own sandbox on its own branch and opens its own pull request.
Give the key a webhook_url and each turn's end arrives as run.completed, run.failed or run.cancelled, signed per Standard Webhooks, with data.session_url to read for the pull request link. A key may have at most max_concurrent runs in progress at once, 4 by default, and starting one more is not refused by Rush: it answers 202 with status: "queued", so a batch over many Gin services sends every request at once and each queued run starts as an earlier one finishes.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The hard part of a rate limit is not the middleware, it is proving it: the right routes, the right key behind a proxy, a bucket that refills, and tests that do not sleep. The agent writes those tests in the repository's own httptest style and runs the full CI script set in its own sandbox, with Go 1.21 to 1.23 as the workflow does, so the pull request arrives with the same checks the merge will run.
Every command and its output stays on the session: the failing test before the middleware existed, the passing run after, the lint result. Several services can get the same treatment at once, each in its own sandbox and pull request, and a follow-up about the limits wakes the same sandbox with the module cache warm.
Frequently asked questions
Which library does it use?
golang.org/x/time/rate, a token bucket from the Go project with no cgo and no server dependency, which keeps go.mod to one new line. For a limit shared across several instances the agent says so in the pull request and leaves a Redis-backed store as a follow-up, since the repository runs on one SQLite file today.
What is the client behind a load balancer?
Whatever c.ClientIP() returns, which depends on Gin's trusted proxies. hello.go never sets them, so the agent reads the proxy addresses from an environment variable and calls SetTrustedProxies; with none set, Gin keys on the direct peer, which would be the balancer for every request.
Will the existing tests still pass with a limiter in front?
They build their own routers in setupRouter() without it, so they are unaffected until the agent mounts the limiter there too. The defaults are high enough for the existing suites, and the new tests lower them through the environment variables rather than editing the old tests.
Can it limit by user rather than by address on authenticated routes?
Yes. After AuthMiddleware(true) the context holds my_user_id, so a second limiter keyed on it can sit on the /api/user and article write routes. Ask for it in the prompt; the default keeps one key, the address, because login and registration have no user yet.