SOP-006: Agent Chat

Document Control

Field	Value
SOP ID	SOP-006
Version	1.0
Status	Active
Last Updated	2024-12

Purpose

This SOP covers using Cursor's Agent Chat for complex, multi-step coding tasks that require autonomous exploration, file creation, and command execution.

Scope

• Opening and using Agent Chat
• Understanding Agent capabilities
• Managing chat sessions
• Checkpoints and history

Prerequisites

• Cursor installed and configured
• Project open in Cursor

---

Procedure

Agent Chat Overview

Agent Core Capabilities:

Category	Actions
Search	Read Files, Search Web, Find Refs
Edit	Create Files, Modify Code, Delete Files
Run	Run Tests, Install Deps, Git Operations

Agent combines all these autonomously to complete your requests.

Step 1: Open Agent Chat

Shortcut: Cmd+I / Ctrl+I

Or:

• Click the chat icon in the sidebar
• Use Cmd+L / Ctrl+L (also opens sidepanel)

The Agent sidepanel opens on the right side of your editor.

Step 2: Ask Agent to Do Something

Type a natural language request:

Simple requests:

• "Add a login button to the header"
• "Create a new React component for user profile"
• "Fix the bug in the authentication flow"

Complex requests:

• "Refactor the entire auth module to use JWT tokens, update all tests, and create migration scripts"
• "Build a REST API with CRUD operations for users, including validation and error handling"

Step 3: Watch Agent Work

Agent Execution Flow:

1. Your Request → You describe what you want
2. Agent Searches Codebase → Finds relevant files
3. Plans Approach → Determines best strategy
4. Makes Changes → Edits files (iterates as needed)
5. Runs Commands → With your approval
6. Verifies Results → Checks the work
7. Reports Completion → Shows what was done

Step 4: Review and Accept Changes

Agent shows diffs for all file changes:

Visual	Meaning
Green lines (+)	Code added
Red lines (-)	Code removed
Checkmark button	Accept individual change
X button	Reject individual change

Bulk Actions:

Action	Shortcut
Accept all changes	Cmd+Enter / Ctrl+Enter
Reject all changes	Cmd+Backspace / Ctrl+Backspace

Step 5: Terminal Command Approval

When Agent needs to run commands, you'll see:

Agent wants to run: npm install express

Options: [Run] [Skip] [Add to Allowlist]

Option	Description
Run	Execute this command once
Skip	Don't run, let Agent try alternative
Add to Allowlist	Always allow this command

Auto-Run Mode

Configure auto-run in Settings to reduce approval prompts. See SOP-008: Terminal Integration.

Step 6: Use Checkpoints

Agent automatically creates checkpoints you can restore:

1. Request 1: "Add user auth" → Checkpoint 1 created
2. Request 2: "Add OAuth support" → Checkpoint 2 created
3. Something went wrong? → Click Checkpoint 1 to restore

Click on any checkpoint in the chat history to restore to that state.

Step 7: Manage Chat Sessions

Multiple Tabs:

• Cmd+T / Ctrl+T: New chat tab
• Each tab maintains separate context and history
• Switch between tabs to work on different tasks

Chat History:

• Opt+Cmd+' / Alt+Ctrl+': Open chat history
• Browse and resume previous conversations
• Export chats to markdown

Navigation:

• Cmd+[ / Ctrl+[: Previous chat
• Cmd+] / Ctrl+]: Next chat
• Cmd+W / Ctrl+W: Close current chat

---

Agent Tools

Agent has access to these tools:

Search Tools

Tool	Description
Read File	Read any file in workspace
List Directory	Browse folder contents
Codebase Search	Semantic search across codebase
Grep	Pattern matching search
Search Files	Find files by name
Web Search	Search the internet
Fetch Rules	Load relevant project rules

Edit Tools

Tool	Description
Edit & Reapply	Modify files with diff view
Delete File	Remove files from project

Run Tools

Tool	Description
Terminal	Execute shell commands
MCP Tools	Use configured MCP servers

---

Tips for Effective Agent Use

Be specific: "Add a blue button" → "Add a blue submit button with hover effect in the login form"

Provide context with @ mentions: @package.json @src/auth/ implement OAuth2 using existing dependencies

Break large tasks into steps: Instead of "build entire app", ask for components one by one

Use Plan mode for complex tasks: Agent creates plan before executing

Reference similar code: "Create a component like @UserCard.tsx but for products"

---

Verification Checklist

• [ ] Cmd+I opens Agent sidepanel
• [ ] Can type requests and receive responses
• [ ] Agent shows diff preview for changes
• [ ] Can accept/reject individual changes
• [ ] Terminal commands show approval prompt
• [ ] Checkpoints appear and can be restored
• [ ] Can open multiple chat tabs
• [ ] Chat history accessible

Troubleshooting

Issue	Solution
Agent not responding	Check network, run diagnostics
Wrong file edits	Add more context with @ mentions
Commands failing	Check terminal output, may need deps
Too many changes	Use Ask mode to plan first
Lost progress	Use checkpoints to restore

See Also

• SOP-007: Agent Modes
• SOP-008: Terminal Integration
• SOP-011: @ Mentions
• Workflow: AI-Assisted Development