How to use Cursor on an existing repo (2026)

Landing in a repo that is not yours — or returning to one you paused months ago — is the most common Cursor case. You do not need the advanced agent flow on day one. You need to open the project without fear, know what the editor can read and ask a question that orients you before you touch a line. This tutorial takes about 22 minutes and ends with a small, reviewable change, not a rewrite.

1. Steps 1

   Open or clone the repo in Cursor

   Two paths. **Local folder:** File → Open Folder and pick the project root (where the README or `package.json` lives). **Clone:** Command Palette (`Ctrl/Cmd+Shift+P`) → «Git: Clone» → paste the remote URL and choose where to save it. Cursor opens the cloned folder. Check the status bar for the repo name and current branch (`main`, `develop`, etc.). If the project needs `npm install`, `pnpm install` or similar, run it in the integrated terminal first — indexing works better with dependencies resolved.

   What you should see: File explorer at the project root, status bar showing the Git branch and a terminal ready to install dependencies if needed.

2. Steps 2

   Trust the folder and let it index

   The first time, Cursor may ask you to **Trust** the authors. Same idea as VS Code: without trust, extensions and terminal stay limited. Accept only for repos you recognize (work, known open source, your own fork). After trusting, Cursor indexes code in the background. Watch the bottom corner: you may see «Indexing…» or a file count. Wait until it finishes or settles before long questions. Huge repos (thousand-file monorepos) take longer — normal. Meanwhile, read the README and `package.json` yourself.

   What you should see: Trust dialog resolved (or gone) and the indexing indicator finished or nearly idle in the status bar.

3. Steps 3

   Read the project map (no AI yet)

   Before chat, orient your eyes. Open in this order: README (if any), stack manifest (`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`), entry folder (`src/`, `app/`, `cmd/`) and how tests run (`npm test`, `pytest`, script in README). Note three things in a scratch pad: command to start, command to test and one folder that looks like the code «heart». This 60-second map avoids questions like «where is everything?» that the model answers with generics.

   What you should see: README and manifest open in tabs, and three noted lines: run, test, main folder.

4. Steps 4

   First useful question in Ask (no code writes)

   Open **Chat** in **Ask** mode (not Agent). Pick one concrete file from the «heart» you noted — e.g. `src/auth/login.ts` — with `@` or by dragging it into chat. Ask something scoped:

   - «Explain what this file does and which three other files it imports.» - «Where is email validated in the login flow? Name paths only, do not edit.» - «Which test covers this module?»

   Ask should not modify files. If you see diff proposals, cancel and confirm you are in Ask, not Agent. The goal is a mental map, not a patch.

   What you should see: Chat panel with the file referenced (`@login.ts`) and an answer citing real repo paths, not invented ones.

5. Steps 5

   Create a branch before you change anything

   When you understand a slice of the code and want to try a small change, **stop**. Create a branch: in the integrated terminal `git checkout -b explore/cursor-first-change` or from the Source Control UI. The branch lets you discard everything with a reset if the next step goes wrong. Pick a safe change: a doc comment, a debug `console.log` you will remove, a test that already fails and you want to understand, or a UI string typo. Do not pick refactors or migrations on day one.

   What you should see: Status bar showing the new branch name and `git status` clean or holding only your future edits.

6. Steps 6

   A small change with Agent and diff review

   Now open **Agent** with a minimal job:

   - Outcome: [one line, e.g. «fix the typo on the login button»] - Files allowed: only the file you already read - Do not touch: tests, CI, dependencies, other modules

   Ask to see the diff before accepting everything. Open each hunk: does it make sense? Extra files? If the diff crosses ~30 lines for a typo, reject and narrow. Accept only what you understand. This step is review practice, not speed.

   What you should see: Diff of one or two files, change matching the job, no surprise files in the modified list.

7. Steps 7

   Run the project scripts and close or revert

   In **your** terminal, run the test or lint command you noted at the start (`npm test`, `make test`, whatever the README says). If it passes and the change was intentional, commit on the branch with a clear message or leave the branch for a PR later. If something unexpected fails, paste the error into a fresh Ask before asking for more edits. If the experiment was not worth keeping, `git checkout -- .` or delete the branch. Day-one success is **understanding the repo and knowing how to revert**, not mystery code on disk.

   What you should see: Terminal with the project script run (green or a readable error) and working tree under control: commit on branch or revert done.