README.md
gitcafe-agent-kit
Working fixes for gaps in the public GitCafe surface, built and tested only against public APIs.

Real turbo 2.11.11 against the cache server in this repo: 2.6 s cold, 11 ms restored from the remote cache.
An independent, unofficial project. It uses only what GitCafe publishes: the REST/OpenAPI spec, the cafe CLI, MCP, the docs and llms.txt. Every claim is in FINDINGS.md, marked verified, documented only or not reproduced, with the exact steps.
What's inside
| Problem | Fix | Status | |
|---|---|---|---|
openapi-slicer | The OpenAPI file is 2.09M characters and its ids look like getApiReposByOwnerByRepoPullsByPr | Verb-style ids (getPullRequest), per-tag slices, one file per operation, a 59K-char index | Verified against the live spec |
cache | actions/cache is "Not yet" in GitCafe Actions | A Turborepo-compatible remote cache server (disk or S3/R2) and a drop-in gitcafe-cache action | Verified with real turbo and a local S3. Not run on a GitCafe runner, see below |
rate-guard | All credentials of an account share one budget and success responses don't say what's left | Per-agent sliding-window guard that learns the policy from RateLimit-Policy | Verified, 28-request benchmark on a real account |
task-runner | No documented way to turn an issue into a reviewed stack | Claim issue, git worktree, run your agent, stack submit --dry-run, then submit and comment with provenance | Verified end to end on a real private repo |

Quick start
Needs Node 24+ (it runs the .ts files directly, no build step) and Bun for the cafe CLI.
| 1 | git clone https://git.cafe/findmalek/gitcafe-agent-kit && cd gitcafe-agent-kit |
| 2 | node --test packages/*/test/*.test.ts |
Slice the API spec
| 1 | node packages/openapi-slicer/src/cli.ts # fetches the live spec into out/openapi |
| 1 | out/openapi/INDEX.md one line per operation, ~15K tokens |
| 2 | out/openapi/ops/listPullRequests.json one operation plus the schemas it needs |
| 3 | out/openapi/by-tag/pull-requests.json a whole area |
Ids are pinned in packages/openapi-slicer/operation-id.lock.json, so a spec update can't silently rename the ones you already use. See BEFORE_AFTER.md for the numbers. Even sliced, listPullRequests is about 11K tokens because the response schemas are deep.
Run a Turborepo remote cache
| 1 | CACHE_TOKENS=change-me node packages/cache/src/main.ts |
| 2 | |
| 3 | export TURBO_API=http://127.0.0.1:3000 TURBO_TOKEN=change-me TURBO_TEAM=my-team |
| 4 | npx turbo run build |
| env | meaning |
|---|---|
CACHE_TOKENS | comma-separated bearer tokens (required) |
CACHE_DIR | store on disk (default .cache/turbo) |
S3_BUCKET, S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_PREFIX | store in S3 or R2 instead |
PORT, HOST | listen address (default 127.0.0.1:3000) |
Teams are isolated by TURBO_TEAM. remoteCache.signature works: artifacts signed with a different key are treated as misses. The Turborepo client calls /v8/artifacts/..., which the published spec omits.
Use the cache in a workflow
GitCafe fetches remote actions from github.com, so reference it there and pin a commit SHA:
| 1 | - uses: FindMalek/gitcafe-agent-kit/packages/cache/action@main |
| 2 | with: |
| 3 | path: node_modules |
| 4 | key: deps-${{ hashFiles('package-lock.json') }} |
| 5 | restore-keys: deps- |
| 6 | bucket: ${{ secrets.CACHE_BUCKET }} |
| 7 | endpoint: https://<account>.r2.cloudflarestorage.com |
| 8 | access-key-id: ${{ secrets.CACHE_KEY_ID }} |
| 9 | secret-access-key: ${{ secrets.CACHE_SECRET }} |
Without credentials it warns and does nothing, so it never breaks a build. Cache entries are trusted: anyone holding the bucket credentials can poison them, so give pull-request jobs a separate prefix.
Guard an agent's API budget
| 1 | import { createGuard } from './packages/rate-guard/src/guard.ts'; |
| 2 | |
| 3 | const guard = createGuard(myTransport, { share: 0.2 }); // this agent may use 20% of the account budget |
| 4 | const reply = await guard.request(req); // waits instead of getting a 429 |
It sends one probe request, learns the real quota from RateLimit-Policy, then allows at most share × quota requests in any window. On a 429 it pauses the whole agent for Retry-After and backs off if it repeats. Benchmark: node packages/rate-guard/bench/bench.ts (28 requests, about a minute).
Turn an issue into a stack
| 1 | node packages/task-runner/src/cli.ts \ |
| 2 | --repo owner/name --issue 12 --handle me --repo-dir . \ |
| 3 | --agent-name my-agent --model my-model -- ./my-agent.sh |
It stops after cafe stack submit --dry-run unless you add --submit. Claiming is best effort: GitCafe has no lease, so the runner assigns the issue, re-reads it and backs off if someone else is also assigned.
What was and wasn't verified
- Verified here: slicer output validates; real
turbohits and misses against the server; the cache action's restore, save, prefix fallback and failure modes against a local SigV4-checked S3; the guard on a real account; the task runner on a real private repo. - Not verified: the cache action on a GitCafe runner (hosted runners are limited to admitted organizations), Cloudflare R2 specifically, and a real HTTP 429 (provoking one would breach the acceptable-use policy).
- Not reproduced: two claims from earlier research, an MCP/docs contradiction on
commit_changesand a Link-header/cursor mismatch.FINDINGS.mdsays what was checked.
Development
| 1 | node --test packages/*/test/*.test.ts # 13 tests |
| 2 | packages/cache/e2e/action.sh # action against a local S3, needs rclone |
| 3 | packages/cache/demo/record.sh # re-record the demo that the GIF is made from |
MIT licensed. Not affiliated with GitCafe.