GitHub But Fast

GitHub, but with fewer model/tool round trips.

GitHub But Fast (GBF) is a read-only Code Mode gateway for GitHub. It lets an MCP-capable agent fan out many fresh GitHub reads inside one sandboxed execute call, filter the results there, and return only the compact context the model needs.

Current stable line: v0.2 (package.json version 0.2.0).

GBF is an acceleration layer, not a source of truth. GitHub remains authoritative. Keep the client's normal GitHub integration available for writes and as a fallback.

Why

Without GBF, a repository takeover often becomes:

model -> fetch file -> model -> fetch issue -> model -> fetch comments
      -> model -> fetch PR -> model -> fetch CI -> ...

With GBF:

agent
  -> execute
       |-> many fresh GitHub reads in parallel
       |-> grep/filter/slice inside the sandbox
       `-> one compact result
  -> normal GitHub integration only when a write is needed

The stable MCP surface intentionally has only two tools:

• execute — the normal fast path. Prefer one call with Promise.all() for independent reads.

• search — OpenAPI endpoint discovery when genuinely needed.

Related MCP server: CodeAudit MCP

Real benchmark

A real Claude Opus ARTI Control Tower workload was used as the acceptance benchmark rather than a toy microbenchmark.

The accepted v0.2 run covered the canonical branch, authority issue/comment tail, handoff comments, PR/issue state, code search, and ten source/doc files in one outer execute call. This is the primary success criterion: fewer model-visible round trips without sacrificing fresh GitHub reads.

See docs/BENCHMARK.md for the benchmark gate.

Safety model

GBF v0.2 is deliberately read-only:

• generated/model code may use only GET or HEAD;

• /repos/{owner}/{repo}/... is restricted to GITHUB_ALLOWED_REPOS;

• /search/* requires explicit allowlisted repo:owner/name qualifiers;

• canonical-path validation rejects path/host escape tricks;

• host-side policy revalidates every request immediately before GitHub access;

• the GitHub App should itself have read-only permissions and be installed only on selected repositories;

• GitHub App credentials and installation tokens never enter the QuickJS sandbox;

• oversized GitHub responses are rejected with a narrowing/pagination hint;

• GitHub Contents API file responses are normalized server-side to decoded UTF-8 content so clients do not need base64 helpers.

The local QuickJS sandbox does not expose Node process, require, arbitrary fetch, the filesystem, or a shell.

Recommended deployment: local-first

The stable setup runs the sandbox on your own machine and exposes it remotely through a Cloudflare Tunnel when needed:

ChatGPT / Claude / Cursor / other MCP client
                  |
                  | HTTPS
                  v
        Cloudflare Tunnel
                  |
                  v
        127.0.0.1:8787/mcp
                  |
                  v
       GBF local QuickJS
                  |
                  v
          GitHub App -> GitHub

This keeps the compute local, requires no paid Dynamic Workers plan, and lets the endpoint disappear naturally when the local process is stopped.

Cloudflare Worker support remains in the repository as an optional hosted path.

Quick start

Requirements: Node.js 22+ and a read-only GitHub App installed on the repositories you want GBF to read.

npm install

Create .env.local (never commit it):

GITHUB_APP_ID=...
GITHUB_INSTALLATION_ID=...
GITHUB_PRIVATE_KEY_FILE=...
GITHUB_ALLOWED_REPOS=owner/repo-a,owner/repo-b
GITHUB_RESPONSE_MAX_BYTES=1500000
MCP_BEARER_TOKEN=...
# Optional; enables OAuth discovery for ChatGPT/custom MCP clients.
GBF_PUBLIC_ORIGIN=https://gbf.example.com
GBF_HOST=127.0.0.1
GBF_PORT=8787

Local-only server:

npm start

Windows/local stack after placing portable cloudflared.exe under tools/ and configuring a named tunnel called gbf:

npm run up

Health endpoint:

GET http://127.0.0.1:8787/health

MCP endpoint:

POST/GET https://YOUR-HOSTNAME/mcp

Authentication remains backward-compatible with Authorization: Bearer <MCP_BEARER_TOKEN>. Compatible clients may also use the optional X-GBF-Token API-key header. When GBF_PUBLIC_ORIGIN is configured, GBF additionally exposes an OAuth Authorization Code + PKCE flow with refresh-token support for hosted clients such as ChatGPT. See docs/CHATGPT.md.

Client usage

Once GBF is connected, this short instruction is usually enough:

Use GitHub But Fast (GBF) for heavy GitHub reads so you do not burn many model-visible tool calls. Prefer one `execute` call with `Promise.all()` and filter/compact inside the sandbox. Use normal GitHub tooling only for writes or when GBF is unavailable. GitHub remains source of truth.

For Control Tower / multi-file review work, use the stronger template in docs/PROMPTING.md.

Practical rules for agents

• Prefer execute directly for known GitHub REST reads; do not call search reflexively.

• Fan out independent reads with Promise.all().

• Grep/filter/slice inside the sandbox and return a compact object.

• Contents API file responses already contain decoded UTF-8 content; do not base64-decode them.

• Keep output below the client's tool-result truncation limit.

• For non-default canonical branches, prefer direct tree/contents reads plus sandbox filtering instead of assuming GitHub code search indexes that branch.

• Use the normal GitHub connector for comments, branches, PR mutations, merges, workflow reruns, or other writes.

Common direct-read endpoints

These usually do not require search first:

GET /repos/{owner}/{repo}/contents/{path}?ref={branch-or-sha}
GET /repos/{owner}/{repo}/issues/{number}
GET /repos/{owner}/{repo}/issues/{number}/comments?per_page=100
GET /repos/{owner}/{repo}/pulls/{number}
GET /repos/{owner}/{repo}/commits/{ref}
GET /repos/{owner}/{repo}/actions/runs
GET /search/code?q=...+repo:{owner}/{repo}
GET /rate_limit

Development

npm test
npm run typecheck
npm run build
npm run smoke:local

CI covers Windows and Ubuntu. The Worker dry-run build is retained even though the recommended stable deployment is local-first.

Project docs

• docs/AGENT_TOOLING_RULEBOOK.md — operational rules learned from real ChatGPT/Claude/swarm experiments

• docs/PROMPTING.md — reusable prompts and read patterns

• docs/BENCHMARK.md — acceptance benchmark and measurement rules

• docs/SETUP.md — setup checklist

• docs/GITHUB_APP.md — minimal read-only GitHub App configuration

• docs/CHATGPT.md — OAuth setup and disposable ChatGPT coexistence gate

• docs/ARCHITECTURE.md — trust boundaries and failure model

• docs/ROLLOUT.md — client rollout gates

• CHANGELOG.md — stable milestones

Non-goals

GBF v0.2 does not provide GitHub mutation tools, agent orchestration, a second source of truth, or unrestricted local shell/worktree access. If writes are ever added, they should be a separate, explicit, approval-aware lane rather than unrestricted Code Mode.

License

MIT. Portions of the architecture and server pattern are adapted from Cloudflare's MIT-licensed Code Mode examples; see NOTICE.