How Cursor AI Understands Your Whole Codebase — And How to Leverage It in a Serverless Lambda

A developer outlined a method for giving Cursor AI full-repository context by using the SDK's uploadRepoTree helper to send a compressed snapshot of an entire codebase to the service, enabling suggestions that respect project-wide architecture rather than isolated files. The writeup also details packaging the Cursor SDK for AWS Lambda on Node 22, including ESM configuration, dependency pinning, and subscribing to the SDK's diagnostics_channel event stream for incremental suggestion delivery.

Cursor AI can scan an entire repository in seconds and give line‑by‑line suggestions, but most engineers treat it like a simple autocomplete. Learn why that mindset wastes the tool’s power and how to unlock full‑context code generation in production. Why it matters – An LLM large language model is a statistical engine that predicts the next token word or symbol based on everything it has seen. If you feed it just one file, it can only guess based on that file’s local symbols. Give it the whole repository, and the model can see relationships across modules, shared types, and project‑wide conventions. Think of it like a detective who reads the entire case file instead of just the last paragraph before writing a report. Key terms How to give Cursor the whole repo – Cursor’s SDK has a helper called uploadRepoTree . It walks the directory, reads each file, and sends a compressed snapshot to the service. The service then builds the context internally, so every subsequent suggest call can reference any file. js import { Cursor } from "cursor"; / Send an entire repository to Cursor so it can build a global view. @param repoPath Absolute path on the Lambda’s /tmp storage where the repo lives. @returns A repoId that you’ll use for later suggestion calls. / async function uploadWholeRepo repoPath: string : Promise<string { const cursor = new Cursor { apiKey: process.env.CURSOR API KEY } ; // uploadRepoTree recursively reads files, strips binaries, and returns an identifier. const { repoId } = await cursor.uploadRepoTree { root: repoPath, // optional: ignore patterns node modules, .git, etc. ignore: "node modules/ ", ".git/ " , } ; console.log ✅ Uploaded repo, got repoId=${repoId} ; return repoId; } In plain English – By sending the whole repo once, you give the AI a “bird’s‑eye view” of your project, enabling it to suggest changes that respect the overall architecture instead of isolated snippets. Why the setup matters – A Lambda runs in a constrained environment limited /tmp space, short cold‑start time . If you bundle the SDK incorrectly, you might hit the require esm gotcha: Node 22 treats ESM modules differently, and some older Lambda layers silently fail to load them, leading to runtime errors you won’t see in logs. Step‑by‑step packaging mkdir cursor-lambda && cd cursor-lambda npm init -y Pin exact versions; these are the ones verified to work with Node 22 on Lambda npm install cursor@2.4.1 @aws-sdk/client-lambda@3.560.0 type: "module" field package.json so Node treats your code as ESM, matching the Cursor SDK. { "name": "cursor-lambda", "version": "1.0.0", "type": "module", // <-- tells Node to use ESM import syntax "dependencies": { "cursor": "2.4.1", "@aws-sdk/client-lambda": "3.560.0" } } node modules Tip – Keep the zipped package under 50 MB. If it grows larger, enable Lambda Layers for the SDKs instead of bundling them directly. diagnostics channel Why streaming helps – Cursor can return suggestions as they are generated, rather than waiting for the entire response. In a PR‑assistant, you want to start posting early feedback to keep the conversation fast. diagnostics channel is a built‑in Node feature that lets you listen to custom events emitted by the Cursor SDK without polluting your own code. Key term Enabling the channel – The Cursor SDK emits a channel called "cursor.suggestion" for each token it generates. You subscribe once at the top of the Lambda, then each suggest call will push events into the same channel. js import { createChannel, channel } from "node:diagnostics channel"; / Subscribe to the "cursor.suggestion" channel. Every time Cursor generates a piece of a suggestion, this listener runs. / function startSuggestionStream repoId: string, filePath: string { const suggestionChannel = channel "cursor.suggestion" ; // The listener receives an object with repoId , filePath , and the text chunk. suggestionChannel.subscribe msg = { if msg.repoId == repoId || msg.filePath == filePath return; // For demo purposes we just log; in production you would buffer and send later. console.log 🧩 Received chunk for ${filePath}: ${msg.text} ; } ; } In plain English – Think of the channel as a walkie‑talkie: the SDK talks, your code listens, and you can react to each piece of the conversation as it arrives. Why you must be explicit – Cursor enforces a per‑minute token quota. When you exceed it, the service returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. The SDK, by default, automatically retries the request up to three times. In a Lambda this hidden retry can stretch the execution beyond the timeout, and you’ll see latency spikes in CloudWatch that look like “random slow calls.” Disabling auto‑retry – Pass { retry: false } when creating the client, then handle the CursorRateLimitError yourself. js import { Cursor, CursorRateLimitError } from "cursor"; / Create a Cursor client that does not automatically retry. / function makeCursorClient : Cursor { return new Cursor { apiKey: process.env.CURSOR API KEY , // Turn off the SDK’s built‑in retry logic. retry: false, } ; } / Wrapper that calls cursor.suggest and deals with 429 errors. / async function safeSuggest client: Cursor, params: Parameters<Cursor "suggest" 0 : Promise<void { try { await client.suggest params ; } catch err { if err instanceof CursorRateLimitError { // The error object contains the raw Retry-After header value. const waitSec = Number err.retryAfter ; console.warn ⚠️ Hit rate limit, waiting ${waitSec}s before retry ; // Simple back‑off – Lambda can await a timeout. await new Promise r = setTimeout r, waitSec 1000 ; // Retry once manually; you could add exponential back‑off here. await client.suggest params ; } else { // Re‑throw unknown errors so Lambda records a failure. throw err; } } } Tip – Log the retryAfter value each time you hit 429. Over a week you can spot patterns e.g., every 10 seconds during CI bursts and adjust your webhook frequency accordingly. Why this example is useful – It demonstrates the complete flow: /tmp , uploads the whole tree to Cursor. suggest , streaming results via Full handler TypeScript, heavily commented . js import { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda"; import { execSync } from "node:child process"; import { promises as fs } from "node:fs"; import { join } from "node:path"; import { Cursor } from "cursor"; import { LambdaClient, InvokeCommand, } from "@aws-sdk/client-lambda"; import { channel } from "node:diagnostics channel"; / Helper: clone the repo to the Lambda's /tmp directory. Git is available in the Lambda runtime Amazon Linux . / async function cloneRepo repoUrl: string, commitSha: string : Promise<string { const dest = join "/tmp", "repo" ; // Clean up any previous run. await fs.rm dest, { recursive: true, force: true } ; execSync git clone ${repoUrl} ${dest} , { stdio: "ignore" } ; execSync git -C ${dest} checkout ${commitSha} , { stdio: "ignore" } ; return dest; } / Helper: post a comment to GitHub simplified; in production use Octokit . / async function postGitHubComment owner: string, repo: string, prNumber: number, body: string { const token = process.env.GITHUB TOKEN ; const url = https://api.github.com/repos/${owner}/${repo}/issues/${prNumber}/comments ; const payload = JSON.stringify { body } ; execSync curl -s -X POST -H "Authorization: token ${token}" -H "Content-Type: application/json" -d '${payload}' ${url} ; } / Main Lambda entry point – receives the GitHub webhook payload. / export const handler = async event: APIGatewayProxyEvent : Promise<APIGatewayProxyResult = { // ----------------------------------------------------------------- // 1️⃣ Extract useful data from the webhook. // ----------------------------------------------------------------- const payload = JSON.parse event.body ?? "{}" ; const pr = payload.pull request; const repoUrl = pr.head.repo.clone url; const commitSha = pr.head.sha; const changedFiles: string = payload.pull request.changed files ? payload.pull request.changed files.map f: any = f.filename : ; // fallback if not provided // ----------------------------------------------------------------- // 2️⃣ Clone repo into /tmp and upload whole‑repo context to Cursor. // ----------------------------------------------------------------- const repoPath = await cloneRepo repoUrl, commitSha ; const cursor = new Cursor { apiKey: process.env.CURSOR API KEY , retry: false } ; const repoId = await cursor.uploadRepoTree { root: repoPath, ignore: "node modules/ ", ".git/ " , } ; // ----------------------------------------------------------------- // 3️⃣ Set up diagnostics channel to collect suggestion chunks. // ----------------------------------------------------------------- const suggestionChannel = channel "cursor.suggestion" ; const suggestions: Record<string, string = {}; suggestionChannel.subscribe msg = { const key = ${msg.repoId}|${msg.filePath} ; if suggestions key suggestions key = ; suggestions key .push msg.text ; } ; // ----------------------------------------------------------------- // 4️⃣ For each changed file, ask Cursor for line‑by‑line suggestions. // ----------------------------------------------------------------- for const relPath of changedFiles { const absPath = join repoPath, relPath ; const fileContent = await fs.readFile absPath, "utf-8" ; // Start listening before we send the request. startSuggestionStream repoId, relPath ; // Wrap the call so we can handle rate‑limit errors. await safeSuggest cursor, { repoId, filePath: relPath, // Provide the full content; Cursor will use the whole‑repo context internally. content: fileContent, // Ask for a diff‑style suggestion. mode: "diff", } ; } // ----------------------------------------------------------------- // 5️⃣ Assemble a markdown comment with the collected diffs. // ----------------------------------------------------------------- let commentBody = " 🤖 Cursor AI suggestions\n\n"; for const key of Object.keys suggestions { const , filePath = key.split "|" ; const diff = suggestions key .join "" ; commentBody += \ ${filePath}\ \n\ \ \ diff\n${diff}\n\ \ \ \n ; } // ----------------------------------------------------------------- // 6️⃣ Post the comment back to the PR. // ----------------------------------------------------------------- await postGitHubComment pr.base.repo.owner.login, pr.base.repo.name, pr.number, commentBody ; return { statusCode: 200, body: JSON.stringify { message: "Suggestions posted" } , }; }; / Helper used earlier: start streaming for a specific file. / function startSuggestionStream repoId: string, filePath: string { // No extra work needed beyond the subscription already set up; // this function exists for readability. } In plain English – The handler glues together three moving parts: a fresh copy of the repo, Cursor’s whole‑repo understanding, and a streaming channel that lets us push suggestions to GitHub as soon as they appear. Gotchas highlighted in the code require esm "type": "module" the import statements work; if you forget this, Node will throw “Cannot use import statement outside a module.” Key points you can act on today CursorRateLimitError yourself so Lambda timeouts stay predictable. With these steps you can move from treating Cursor as a fancy autocomplete to using it as a full‑context code reviewer that runs on demand, cost‑effectively, in a serverless environment. Happy coding Transparency notice This article was written with the help of an AI system — Groq https://groq.com GPT OSS 120B . Published: 2026-09-17 · Primary focus: CursorAI All code blocks are intended to be correct and runnable, but please verify them against Cursor's official docs https://docs.cursor.com before using in production. Find an error? Drop a comment — corrections are always welcome.