Setup fundamentals
Table of Contents
- 1. Overview
- 2. Install Cursor
- 3. Cursor setup
- 4. Terminal basics
- 5. Package managers
- 6. Git basics
- 7. Troubleshooting
- 8. Reference
1. Overview
Cursor is an AI code editor. It uses large language models to help you generate, edit, and understand code.
Key features:
| Feature | Description | Shortcut |
|---|---|---|
| Tab | Multi-line autocomplete that predicts your next edit | Tab |
| Inline Edit | Select code and describe changes | Cmd+K / Ctrl+K |
| Agent | Build features and make changes across multiple files | Cmd+I / Ctrl+I |
| Plan | Create step-by-step plans before implementing | Cmd+P / Ctrl+P |
| Ask | Ask questions about your codebase | User assignable |
| Debug | Diagnose and fix bugs using runtime traces | User assignable |
| Agent Review | Review all changes against main branch for issues | User assignable |
| Multitask | Delegate work to parallel background subagents | User assignable |
Learn more: Cursor Concepts
2. Install Cursor
- Download Cursor and run the installer
- Create a GitHub account if you don't have one
- Enable two-factor authentication (2FA) in your GitHub account settings
3. Cursor setup
Getting started
First launch
When you open Cursor for the first time:
- Create a new folder for your project (or open an existing one)
- Press
Cmd+I(macOS) orCtrl+I(Windows) to open Agent mode - Try a simple prompt like "Create a hello world HTML file"
You're now using Cursor. The sections below explain additional setup and tools as you need them.
GitHub integration
Connecting your GitHub account lets you push code to repositories and collaborate with others. Sign in once and Cursor will remember your credentials.
- Press
Cmd+Shift+P(macOS) orCtrl+Shift+P(Windows) - Type "GitHub: Sign in" and press Enter
- Authorize Cursor in the browser popup
Once signed in, you can ask the agent to commit and push changes for you. It writes descriptive commit messages automatically. You can also use the Source Control tab in the left sidebar for manual control.
Docs: Cursor GitHub Integration
Configuration (optional)
These settings improve your workflow but aren't required to get started.
Enable autosave
Add this to your User Settings JSON (Cmd+Shift+P > "Preferences: Open User Settings (JSON)"):
"files.autoSave": "afterDelay",
"files.autoSaveDelay": 1000
This removes the need to manually save. Changes appear in git status automatically.
Install CLI command
Open any folder from the terminal with the cursor command:
-
Open command palette:
Cmd+Shift+P(macOS) orCtrl+Shift+P(Windows) -
Search: "Shell Command: Install 'cursor' command in PATH"
-
Open any folder from terminal:
cursor .
Project structure
your-project/
├── .cursor/
│ └── rules/
│ └── project.md # Your project rules
├── .cursorignore # Files agent should ignore
└── ...
Sample .cursorignore
node_modules/
dist/
build/
Docs: Cursor Rules
Using the agent
Context symbols
Use @ symbols in prompts to give the agent more context:
@file- browse files or folders@<filename>- include specific file/folder@docs- include external documentation@git- reference git changes and diffs@browser- open an embedded browser tab for testing and debugging@terminals- browse terminal windows
Run modes
Go to Cursor Settings > Agents and configure Run mode:
| Option | Behavior |
|---|---|
| Allowlist | Tools run automatically only when they match your allowlist. Everything else asks for approval. |
| Allowlist (with Sandbox) | Tools auto-run in a sandbox when possible. If sandbox is unavailable, falls back to your allowlist or asks. Recommended default. |
| Auto (with Sandbox) | Tools auto-run in a sandbox by default, with fewer prompts. |
| Run Everything (Unsandboxed) | Only recommended in isolated environments (e.g. VMs or containers). |
Three layers govern agent network access: Fetch Domain Allowlist in Cursor Settings (local IDE, user-scoped), .cursor/sandbox.json at the repo root (committed, authoritative for sandboxed + cloud agents), and a per-user cloud-agent global allowlist.
Keyboard shortcuts
| Action | macOS | Windows |
|---|---|---|
| Toggle left sidebar | Cmd+B | Ctrl+B |
| Toggle Agent mode | Cmd+I | Ctrl+I |
| Toggle Plan mode | Cmd+P | Ctrl+P |
| Cycle agent modes | Cmd+. | Ctrl+. |
| Cycle agent modes from chat input | Cmd+. | Ctrl+. |
| Cycle reasoning effort for selected model | Cmd+Shift+/ | Ctrl+Shift+/ |
| Toggle Agent/Editor view | Cmd+E | Ctrl+E |
4. Terminal basics
The terminal is an application for executing text commands instead of using a graphical interface. The shell is the program that interprets your commands (bash, zsh, etc.). On macOS, use the built-in Terminal app. On Windows, use Git Bash (installed with Git).
Commands:
| Command | Description |
|---|---|
pwd | Print current directory path |
ls | List files in current directory |
cd folder | Change to specified directory |
cd .. | Move up one directory level |
cd ~ | Change to home directory |
mkdir folder | Create a new directory |
cat file | Display file contents |
Keyboard shortcuts:
| Key | Action |
|---|---|
| Tab | Cycle through options |
| Right | Autocomplete suggestion |
| Up | Previous command |
| Ctrl+C | Cancel current command |
5. Package managers
A package manager is a tool that installs and updates software from the command line. Instead of downloading installers from websites, you run a single command.
| macOS | Windows |
|---|---|
Git comes pre-installed. Run git --version to verify. | scoop install git |
6. Git basics
Git is version control software that tracks changes to your code. It allows you to create commits (saved states), revert to previous versions, upload to hosting platforms like GitHub, and merge work from multiple branches.
Key concepts
| Term | Meaning |
|---|---|
| Repository | A folder tracked by Git that contains your project and its history |
| Working directory | Current state of files in your repository |
| Unstaged changes | Modified files not yet selected for commit |
| Staged changes | Changes selected to be included in the next commit |
| Commit | A saved snapshot of staged changes |
Staging allows you to commit specific changes while leaving others uncommitted. Use git add <file> to stage individual files, or git add . to stage everything.
First time setup
Run these once to configure your identity:
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
Essential commands
| Command | Description |
|---|---|
git init | Initialize a new repository |
git clone <url> | Download an existing repository |
git status | Show modified files |
git add . | Stage all changes for commit |
git commit -m "msg" | Save staged changes with a message |
git push | Upload commits to remote repository |
git log --oneline | List commit history |
git log --oneline --graph | List commit history as a tree |
Inspecting agent changes
When the agent makes changes, use these commands to see what happened:
git status # Show what files changed
git log --oneline -5 # View recent commit history
git show HEAD -- path/to/file # View the latest committed version of a file
Undo commands
Discard uncommitted changes:
| Command | Description |
|---|---|
git restore . | Discard unstaged changes only (keeps staged changes) |
git checkout HEAD -- <file> | Restore a single file to its last committed state |
git reset --hard | Discard all changes (both staged and unstaged) |
Undo commits:
| Command | Description |
|---|---|
git reset --soft HEAD~1 | Undo last commit, keep changes staged |
git reset --hard HEAD~1 | Undo last commit, discard changes |
Optional: Git GUI
A dedicated Git GUI makes it easier to browse many commits at once in a larger view.
| App | Install | Notes |
|---|---|---|
| Sourcetree | brew install --cask sourcetree | Free, polished. macOS + Windows |
Docs: Git
7. Troubleshooting
| Problem | Solution |
|---|---|
| Cursor features not working | Try running git init, then close and reopen folder |
| GitHub authentication fails | Re-run "GitHub: Sign in" from command palette (Cmd+Shift+P) |
| Agent can't see my files | Verify .cursorignore is not excluding them |
| New packages not working | Run npm install manually after adding dependencies |
8. Reference
Tools
- Homebrew (macOS package manager)
- Scoop (Windows package manager)
- Sourcetree (Git GUI)
Documentation
- Cursor - Editor documentation
- Cursor Concepts - Core features and AI foundations
- Cursor GitHub Integration - Connect Cursor to GitHub
- Cursor Rules - Project context rules
- Git - Version control
- GitHub - Platform documentation