Cursor – complete guide to AI agent capabilities and configuration

May 2026

Cursor is a code editor built on VS Code that has revolutionized the way developers work with AI since 2023. Unlike simple plugins for chatting with a language model, Cursor treats AI as a full participant in the software development process – an agent that reads files, executes commands in the terminal, reviews errors, writes and modifies code, and even opens pull requests on GitHub. This article is a detailed overview of what Cursor can do, and – more importantly – how to configure it so that agents work better, more efficiently, and in line with your expectations.

AI interaction modes

Cursor offers several modes of interaction with the model:

Ask

Read-only mode. The agent can browse files, search code, and answer questions, but makes no changes. Great for exploring an unfamiliar codebase, understanding architecture, or explaining code snippets.

Agent (default working mode)

A full-featured agent with access to all tools: it can read and write files, run commands in the terminal, search code, install packages, clone repositories, open browsers, invoke MCP tools, and delegate tasks to subagents. The vast majority of work happens in this mode.

Plan

Read-only mode designed for planning solutions before implementation. When a task is large, multi-threaded, or has significant architectural trade-offs, Plan mode allows you to discuss the approach before anything is changed in the code.

Inline Edit

Quick editing directly in the editor – select a piece of code, press a keyboard shortcut, and describe the change. Ideal for refactoring a single function, fixing a specific bug, or adding comments.

Tab Completion

Intelligent code completion – Cursor predicts what you'll write next, taking into account the context of the entire project, not just the current file. Supports multi-line suggestions and can propose the next step in a sequence of changes.

Context – the heart of agent work

An agent is only as good as the context it receives. Cursor offers several mechanisms for providing context:

@-mentions

In the chat window you can refer to:
- @file.ts – a specific file
- @folder/ – an entire directory
- @Git – commit history
- @Docs – external documentation (e.g. React, Tailwind)
- @Web – real-time web search
- @Codebase – semantic search across the entire codebase

Attaching files

You can drag files into the chat window or use the attachment button so the agent has access to specific resources – e.g. an error screenshot, a CSV data file, a database schema.

MCP – Model Context Protocol

MCP is an open standard for integrating external tools with AI agents. Cursor supports MCP servers that extend the agent's capabilities with access to external systems.

Examples of available MCP servers:
- Datadog – log, metric, and trace queries
- Linear – ticket and project management
- Sentry – error and issue browsing
- Slack – sending messages, browsing channels
- Databricks – SQL queries, data work
- Stripe – subscription and payment data
- GitHub – pull requests, issues, code review
- PostgreSQL / SQLite – direct database queries

MCP is configured in ~/.cursor/mcp.json (globally) or .cursor/mcp.json (per project). Example configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Canvas – interactive artifacts

Canvas is a newer Cursor feature that allows the agent to create live React apps opened directly alongside the chat window. Instead of pasting a data table in markdown, the agent can render an interactive dashboard, chart, timeline, or data exploration tool.

Canvases are ideal when:
- the result is a standalone analytical artifact – a metrics summary, security audit, report, or architecture review
- data from MCP (Datadog, Databricks, etc.) is the primary deliverable, not an intermediate step
- the result has many rows and would benefit from a visual layout

A canvas file has the .canvas.tsx extension and only imports from cursor/canvas – no external packages, no fetch(). The agent creates it automatically when the topic calls for it.

Rules – persistent agent configuration

Rules are one of Cursor's most powerful configuration mechanisms. They allow for persistent agent instruction – establishing coding standards, project conventions, and architectural patterns that the agent must follow.

Where to store them?

Project rules – in .cursor/rules/ (versioned together with the project, shared across the team).

File format

Rule files have the .mdc extension and contain YAML frontmatter:

---
description: TypeScript standards for this project
globs: **/*.ts
alwaysApply: false
---

# Error handling

Always log errors before re-throwing the exception:

\`\`\`typescript
// ❌ BAD
try {
  await fetchData();
} catch (e) {}

// ✅ GOOD
try {
  await fetchData();
} catch (e) {
  logger.error('Data fetch error', { error: e });
  throw new DataFetchError('Failed to fetch data', { cause: e });
}
\`\`\`

Frontmatter fields

Best practices

• A rule should have one specific goal – don't pack everything into a single file.
• Include concrete examples (good / bad) – the agent learns much better from examples than from abstract descriptions.
• Keep rules under 500 lines – the more concise, the better.
• Use alwaysApply: true for global rules (e.g. response language, commit style).

Examples of useful rules

Language rule (agent always responds in English):

---
description: Agent response language
alwaysApply: true
---
Always respond in English, unless the user explicitly asks for another language.

Style rule for React:

---
description: React component patterns
globs: **/*.tsx
alwaysApply: false
---
- Use functional components, never class components.
- Extract logic into custom hooks (useXxx).
- Co-locate styles with the component (CSS Modules or styled-components).
- Type props using interfaces, not type aliases.

Commit rule:

---
description: Commit message format
alwaysApply: true
---
Commits in Conventional Commits format:
- feat: new feature
- fix: bug fix
- refactor: refactoring without behavior change
- docs: documentation
- test: tests

Example: `feat(auth): add Google OAuth login`

Skills – specialized agent knowledge

Skills are more than rules – they are sets of instructions describing how to perform specific tasks. The agent loads a skill only when the conversation topic indicates it (or when you ask it to). This keeps the context free from irrelevant information.

Where to store them?

• ~/.cursor/skills/skill-name/ – personal skills, available across all projects.
• .cursor/skills/skill-name/ – project skills, versioned with the repository.

Note: Never create skills in ~/.cursor/skills-cursor/ – that is Cursor's internal directory.

Skill structure

my-skill/
├── SKILL.md              # Required – main instructions.
├── reference.md          # Optional – detailed documentation.
├── examples.md           # Optional – usage examples.
└── scripts/              # Optional – helper scripts.
    └── helper.py

SKILL.md format

---
name: sales-analysis
description: Analyzes sales data from CSV, generates reports and charts. Use when the user mentions sales, revenue, monthly reports, or CSV files.
---

# Sales Data Analysis

## Quick start

1. Load the CSV file via pandas.
2. Check column types and missing values.
3. Calculate aggregates (sum, average, trend).
4. Generate a chart using matplotlib.

## Helper scripts

\`\`\`bash
python scripts/validate_csv.py file.csv
# Returns: "OK" or a list of issues
\`\`\`

Key principles for writing skills

The description is critical – the agent uses it to decide when to load the skill. It should contain:
- What the skill does (capabilities)?
- When to use it (trigger scenarios, keywords)?

Example of a good description:

description: Reviews pull requests for quality, security, and compliance with team standards. Use when reviewing a PR, inspecting code changes, or when the user requests a code review.

Conciseness – the agent is intelligent; don't explain the obvious. Write only what the agent wouldn't know on its own.

disable-model-invocation: true – the default option; the skill loads only when explicitly invoked or when the agent selects it based on context.

Examples of useful skills

• code-review – Code review standards for your project, security checklist.
• deploy – Deployment steps (staging → production), checklist of things to verify.
• db-schema – Database structure description, table relationships.
• commit-messages – Preferred format, examples of good and bad messages.
• api-conventions – Endpoint naming standards, response formats, error handling.
• onboarding – Guide for new developers on how to run the project locally.

Hooks – automation around agent events

Hooks are an advanced feature allowing you to run your own scripts or model queries before or after specific agent events. With them you can:

• block dangerous operations (e.g. rm -rf, network commands)
• format files automatically after each edit
• audit what the agent is doing
• inject additional context after a tool is executed
• chain subagents in loops

Where to store them?

• .cursor/hooks.json + .cursor/hooks/ – project hooks
• ~/.cursor/hooks.json + ~/.cursor/hooks/ – user hooks (global)

hooks.json format

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/approve-network.sh",
        "matcher": "curl|wget|nc",
        "failClosed": true
      }
    ],
    "afterFileEdit": [
      {
        "command": ".cursor/hooks/format.sh"
      }
    ]
  }
}

Available events

Example: blocking dangerous commands

#!/bin/bash
# .cursor/hooks/approve-network.sh
input=$(cat)
command=$(echo "$input" | jq -r '.command // empty')

if <span class="text-amber-500/50" title="Nieznany link">[[&quot;$command&quot; =~ curl]]</span>; then
  echo '{
    "permission": "ask",
    "user_message": "This command may send a network request. Do you approve?",
    "agent_message": "Hook blocked the command as a potential network request."
  }'
  exit 0
fi

echo '{ "permission": "allow" }'
exit 0

Example: auto-formatting after edit

#!/bin/bash
# .cursor/hooks/format.sh
input=$(cat)
file=$(echo "$input" | jq -r '.path // empty')

if <span class="text-amber-500/50" title="Nieznany link">[[&quot;$file&quot; =~ \.(ts]]</span>; then
  npx prettier --write "$file" 2>/dev/null
fi

exit 0

Prompt hooks

Instead of a script, you can use a language model to make a decision:

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "type": "prompt",
        "prompt": "Does this command look safe? Only allow read-only operations. Command: $ARGUMENTS",
        "timeout": 10
      }
    ]
  }
}

Prompt hooks are simple to configure, but script hooks are deterministic and auditable – choose based on your needs.

Status line in CLI

Cursor has its own CLI interface (cursor in the terminal) with support for a custom status line above the prompt. It is a script that runs with each conversation update and can display any information.

Configuration in ~/.cursor/cli-config.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.cursor/statusline.sh",
    "padding": 2
  }
}

The script receives a JSON object on stdin with session information – current model, context window usage percentage, working directory, active git branch, vim mode, worktree name, and more.

Example script showing model and context bar:

#!/usr/bin/env bash
input=$(cat)
MODEL=$(echo "$input" | jq -r '.model.display_name')
PCT=$(echo "$input" | jq -r '.context_window.used_percentage // 0' | cut -d. -f1)

BAR_WIDTH=10
FILLED=$((PCT * BAR_WIDTH / 100))
EMPTY=$((BAR_WIDTH - FILLED))
BAR=""
[ "$FILLED" -gt 0 ] && printf -v FILL "%${FILLED}s" && BAR="${FILL// /▓}"
[ "$EMPTY" -gt 0 ] && printf -v PAD "%${EMPTY}s" && BAR="${BAR}${PAD// /░}"

printf "\033[36m[%s]\033[0m ctx %s %s%%\n" "$MODEL" "$BAR" "$PCT"

Output: [Claude Sonnet 4.5] ctx ▓▓▓░░░░░░░ 30%

Subagents and parallel tasks

Cursor Agent can create subagents – specialized processes launched in parallel to handle complex tasks. This is especially useful for:

• exploring a large, unfamiliar codebase (the "explore" agent searches many places simultaneously)
• running isolated experiments in separate git branches (worktrees)
• analyses requiring many independent data sources
• running tests, builds, or deployments in the background

Subagent types

Subagents run in the background and notify the main agent upon completion.

Worktrees – isolated working environments

Cursor supports git worktrees – the ability to have multiple working copies of a repository simultaneously, each on a different branch. Agents can work in separate worktrees independently of each other, without conflicts.

Useful when:
- you want to compare several implementations of the same problem
- you're running a long build in the background while simultaneously working on another feature
- you're testing different approaches to refactoring

Babysitting a PR – agent watching pull requests

The babysit skill implements a scenario where the agent independently supervises a PR until it's ready to merge. In a loop:

1. Checks PR comments (including from bots like Bugbot).
2. Fixes those it agrees with; explains those it's unsure about.
3. Resolves merge conflicts (only when the intent of changes is obvious).
4. Fixes red CI.
5. Pushes changes and watches CI again.
6. Repeats until done.

Split to PRs – splitting large work into small PRs

The split-to-prs skill helps divide a large amount of uncommitted work into several small, reviewable pull requests. Procedure:

1. The agent analyzes the repo state and chat history to understand the intent.
2. Proposes a split (usually the PR title alone is enough).
3. Waits for your approval.
4. Creates branches, commits only the planned files or hunks, pushes, and opens PRs.
5. Keeps a backup before any git operations.

Editor settings configuration

Cursor inherits the full configurability of VS Code. User settings are located in:

Popular Cursor-specific settings:

{
  "cursor.cpp.enablePartialAccepts": true,
  "cursor.chat.showSuggestedFiles": true,
  "cursor.chat.smoothStreaming": true,
  "cursor.composer.shouldAutoScrollToBottom": true
}

Putting it all together – example project configuration

Here's what a well-configured project might look like:

my-project/
├── .cursor/
│   ├── rules/
│   │   ├── typescript-standards.mdc    # TS standards, alwaysApply: false, globs: **/*.ts
│   │   ├── react-patterns.mdc          # React patterns, alwaysApply: false, globs: **/*.tsx
│   │   ├── commit-style.mdc            # Commit format, alwaysApply: true
│   │   └── english-responses.mdc       # Respond in English, alwaysApply: true
│   ├── skills/
│   │   ├── db-schema/
│   │   │   └── SKILL.md                # This project's database schema.
│   │   └── deploy/
│   │       └── SKILL.md                # Deployment procedure.
│   ├── hooks.json                      # Agent event automations.
│   ├── hooks/
│   │   ├── format.sh                   # Auto-format after edit.
│   │   └── approve-network.sh          # Ask before network requests.
│   └── mcp.json                        # Integrations with external tools.

At the user level (globally):

~/.cursor/
├── skills/
│   ├── code-review/
│   │   └── SKILL.md                   # My personal code review style.
│   └── git-workflow/
│       └── SKILL.md                   # My git workflow.
├── hooks.json                         # Global hooks (e.g. rm -rf block).
├── hooks/
│   └── safety-check.sh
└── cli-config.json                    # CLI status line.

Best practices for working with the agent

Be specific in your instructions

The more precisely you describe the task, the better the result. Instead of "fix the bug", write "the calculateTotal function in cart.ts returns undefined when the product list is empty – fix it so it returns 0".

Use @-mentions consciously

Only add what's relevant to the context. An agent with an overloaded context loses efficiency. Point to a specific file instead of an entire folder if that's sufficient.

Read before you accept

Agents make mistakes. Always review proposed changes before approving – especially when modifying configuration files, databases, or deployment scripts.

Iterate in small steps

Instead of one big task (which may fail), break the work into smaller stages. After each stage, check the result, ask questions, adjust direction.

Build a rules foundation

Invest time in writing good rules and skills at the start of a project. It's a one-time investment that pays off with every subsequent conversation with the agent.

Use Plan mode before major changes

Before refactoring a large module, migrating a database, or rewriting critical logic – switch to Plan mode first, discuss the approach, make sure the agent understands the constraints and intentions.

New features (2026)

Cursor CLI as an autonomous terminal agent

Cursor is no longer just an editor. The CLI (cursor) allows you to run the agent directly from the terminal – without opening the graphical interface. Ideal for automation, CI/CD scripts, or working on remote servers via SSH.

Best-of-N runner

The best-of-n-runner subagent runs the same task multiple times in isolated worktrees and returns the best result. Useful when a task has many valid approaches and you care about solution quality, not just speed.

Extended hooks

New hook events give even better control over agent behavior: afterAgentResponse, afterAgentThought, preCompact (before context compression). It's possible to build comprehensive audit and security systems around the agent.

Prompt hooks – policies described in natural language

Instead of writing a bash script for validation, you can describe a security policy in natural language in a prompt hook – Cursor invokes a language model that decides whether the action is allowed. Particularly useful for non-trivial business rules.

Integration with kanban boards and PM tools

Via MCP servers, the agent can now directly read and modify tickets in Linear, Jira, Notion, and similar tools – task context reaches the agent without copy-paste.

Summary

Cursor is not just an "editor with AI" – it's a platform for building your own work environment with an AI agent tailored to your needs. Key configuration mechanisms:

The better the configuration, the less time you spend explaining context to the agent, and the more time on actual work. A well-configured Cursor is an agent that knows your project, your style, and your constraints – and works in line with them from the very first word.

Article written in May 2026. Cursor is actively evolving – some features may only be available in specific plans or versions.

Sources and further reading

1. Cursor Docs – main documentation – overview of all agent features, rules, MCP, skills, and CLI
   cursor.com/docs

2. Hooks | Cursor Docs – complete documentation of the hooks system: events, JSON format, matchers, script examples
   cursor.com/docs/agent/third-party-hooks

3. Agent Skills | Cursor Docs – skills specification: SKILL.md structure, locations, frontmatter, automatic invocation
   cursor.com/docs/context/skills

4. Model Context Protocol (MCP) | Cursor Docs – MCP server configuration, transports (stdio, SSE, HTTP), installation from Marketplace
   cursor.com/docs/context/mcp

5. Canvases | Cursor Docs – canvas.tsx format description, SDK components, workflow for creating interactive artifacts
   cursor.com/docs/agent/tools/canvas

6. Cursor Marketplace – library of ready-made plugins, rules, and MCP servers for one-click installation
   cursor.com/marketplace