# Cursor AI Agent Architecture - Agent & Planning Mode

**Stand**: Februar 2026
**Zweck**: Technische Dokumentation der AI-Agenten-Integration in Cursor (VS Code Fork) als Grundlage fuer die Entwicklung einer eigenstaendigen Chat-Komponente mit API-Zugang

---

## 1. Ueberblick

Cursor ist ein Fork von Visual Studio Code, erweitert um tiefgreifende AI-Faehigkeiten. Im Gegensatz zu VS Code Extensions, die durch die Extension-API limitiert sind, hat Cursor als echter Fork vollen Zugriff auf den Rendering-Pipeline, den AST-Level und die Language Server Infrastructure.

Die AI-Integration besteht aus zwei Hauptkomponenten:

1. **Client (Body)**: Die Electron/VS Code-basierte Desktop-Applikation mit Custom-UI-Elementen (Chat-Sidebar, Composer-Panel, Inline-Completions)
2. **Backend (Brain)**: Cloud-Services fuer LLM-Orchestrierung, Prompt-Konstruktion, Codebase-Indexierung und Embedding-Storage

```
User Interaction
  ↓
Cursor Client (Electron / VS Code Fork)
  ├─> Chat Panel UI (Custom Webview)
  ├─> Composer Panel (Multi-File Editor)
  ├─> Inline Completions (Tab)
  └─> Cmd/Ctrl+K (Inline Edit)
        ↓
  Context Assembly Layer
  ├─> Open Files / Cursor Position
  ├─> Semantic Search (RAG)
  ├─> AST / Language Server Data
  └─> Conversation History
        ↓
  Cursor Backend (Cloud)
  ├─> Prompt Construction
  ├─> Model Routing (GPT / Claude / Gemini / Custom)
  ├─> Tool Orchestration
  └─> Response Streaming
        ↓
  Response Processing (Client)
  ├─> Text Rendering (Markdown)
  ├─> Code Diff Application
  ├─> Tool Call Execution
  └─> Plan/Todo Management
```

---

## 2. Interaction Modes

Cursor bietet vier Modi, die ueber `Ctrl+.` gewechselt werden koennen:

### 2.1 Agent Mode (Standard-Ausfuehrungsmodus)

**Zweck**: Autonomes Implementieren, Refactoring, Bug-Fixing

**Faehigkeiten**:
- Multi-File Exploration und Editing
- Terminal-Kommando-Ausfuehrung (sandboxed)
- Codebase-Suche (semantisch + grep)
- Iterative Verfeinerung mit Compiler/Linter-Feedback
- Parallele Tool-Aufrufe fuer Geschwindigkeit

**Ablauf**:
```
User Prompt
  ↓
Context Assembly
  ├─> user_info (OS, Shell, Workspace)
  ├─> project_layout (File Tree Snapshot)
  ├─> open_files / cursor_position
  └─> edit_history / linter_errors
        ↓
System Prompt Injection
  ├─> Role Definition ("AI coding assistant, pair programmer")
  ├─> Communication Guidelines (Markdown, Code Citations)
  ├─> Tool Calling Rules (15+ Tools)
  ├─> Context Strategy (Parallel Execution, Thorough Exploration)
  └─> Code Change Guidelines (Read before Edit, Fix Lints)
        ↓
LLM Request (POST /v1/chat/completions)
  ├─> model: "claude-4.6-opus" | "gpt-5.2" | ...
  ├─> temperature: 0
  ├─> messages: [system, user_context, user_query]
  ├─> tools: [15+ tool definitions]
  ├─> tool_choice: "auto"
  └─> stream: true
        ↓
Streaming Response
  ├─> Text Chunks (Markdown)
  ├─> Tool Calls (JSON)
  │     ├─> Tool Execution (Client-Side)
  │     └─> Tool Results → Next LLM Turn
  └─> Completion
```

### 2.2 Plan Mode (Planungsmodus)

**Zweck**: Komplexe Features zerlegen, Codebase analysieren, Implementierungsplaene erstellen

**Aktivierung**: `Shift+Tab` im Agent Input oder `Ctrl+.` → Plan

**Kernmerkmal**: Read-Only - es werden keine Aenderungen am Code vorgenommen

**System Reminder bei Plan Mode**:
```
Plan mode is active. The user indicated that they do not want you to execute
yet -- you MUST NOT make any edits, run any non-readonly tools (including
changing configs or making commits), or otherwise make any changes to the
system.
```

**Plan-Mode-Workflow**:
```
User beschreibt komplexe Aufgabe
  ↓
Codebase Research (Read-Only)
  ├─> Semantic Search nach relevanten Dateien
  ├─> File Reading fuer Kontextverstaendnis
  └─> Grep fuer spezifische Symbole
        ↓
Klaerende Fragen an User
  ├─> Anforderungen praezisieren
  ├─> Implementierungsvarianten abklaeren
  └─> Scope eingrenzen
        ↓
Plan-Erstellung (create_plan Tool)
  ├─> Markdown-Dokument mit Datei-Referenzen
  ├─> Code-Beispiele und Snippets
  ├─> Strukturierte Todos mit IDs und Abhaengigkeiten
  └─> Uebersicht (1-2 Saetze)
        ↓
User Review & Inline-Editing
  ├─> Plan direkt im Editor bearbeitbar
  ├─> Todos hinzufuegen/entfernen
  └─> Bei Zufriedenheit: Ausfuehrung starten
```

**Plan-Datenmodell** (`create_plan` Tool):
```json
{
  "name": "Kurzer Plan-Name (3-4 Worte)",
  "overview": "1-2 Saetze Zusammenfassung",
  "plan": "# Plan Title\n\nMarkdown-Inhalt mit Dateireferenzen...",
  "todos": [
    {
      "id": "setup-auth",
      "content": "Auth-Middleware implementieren",
      "dependencies": []
    },
    {
      "id": "implement-ui",
      "content": "Login-Formular erstellen",
      "dependencies": ["setup-auth"]
    }
  ]
}
```

### 2.3 Ask Mode (Frage-Modus)

**Zweck**: Code verstehen, Fragen beantworten ohne Aenderungen
**Einschraenkung**: Read-Only, keine Write-Tools verfuegbar

### 2.4 Debug Mode (Fehlerbehebungs-Modus)

**Zweck**: Systematische Fehleranalyse mit Hypothesen, Log-Instrumentierung, Runtime-Analyse

---

## 3. Communication Protocol

### 3.1 Transport Layer

Cursor kommuniziert mit dem Backend ueber **ConnectRPC** (gRPC-Web Variante) mit **Protocol Buffers (Protobuf)** als Serialisierungsformat.

**Primaerer Endpoint**: `https://api2.cursor.sh`

**Encoding**: HTTP/2 mit binaerer Protobuf-Kodierung im Envelope-Format:
```
[type:1 byte][length:4 bytes Big-Endian][payload:N bytes]
```

### 3.2 Protobuf-Schema (Reverse Engineered)

**Service**: `aiserver.v1.ChatService`

**Kern-Messages**:
```protobuf
message GetChatRequest {
  ModelDetails modelDetails = 1;
  repeated ConversationMessage conversation = 2;
}

message ModelDetails {
  optional string modelName = 1;
}

message ConversationMessage {
  string text = 1;
  MessageType type = 2;

  enum MessageType {
    MESSAGE_TYPE_HUMAN = 0;
    MESSAGE_TYPE_AI = 1;
  }
}
```

**Streaming-Methode**: `StreamChat()` bzw. `StreamUnifiedChatWithTools()`
- Antworten kommen als iterativer Stream
- Jeder Chunk enthaelt ein `text`-Feld mit partiellem Content

### 3.3 OpenAI-kompatibles Chat Completions API

Parallel zum Protobuf-Protokoll nutzt Cursor intern das **OpenAI Chat Completions Format**:

```
POST /v1/chat/completions
```

**Request-Struktur**:
```json
{
  "model": "claude-4.6-opus",
  "temperature": 0,
  "user": "github|user_ID",
  "messages": [
    {
      "role": "system",
      "content": "[System Prompt mit allen Instruktionen]"
    },
    {
      "role": "user",
      "content": "<user_info>...</user_info>\n<project_layout>...</project_layout>"
    },
    {
      "role": "user",
      "content": "<user_query>...</user_query>\n<system_reminder>...</system_reminder>"
    }
  ],
  "tools": [ /* 15+ Tool-Definitionen */ ],
  "tool_choice": "auto",
  "stream": true
}
```

**Kontext-Injection im User-Message**:

| Tag | Inhalt |
|---|---|
| `<user_info>` | OS, Datum, Shell, Workspace-Pfad |
| `<project_layout>` | Dateibaum-Snapshot (einmalig zu Gespraechsbeginn) |
| `<user_query>` | Der eigentliche User-Prompt |
| `<system_reminder>` | Dynamische Modus-Instruktionen (z.B. Plan Mode aktiv) |
| `<open_and_recently_viewed_files>` | Offene und kuerzlich angesehene Dateien |

---

## 4. System Prompt Architektur

Der System Prompt ist das Herzstrueck der AI-Steuerung. Er wird vom Cursor-Backend zusammengebaut und besteht aus folgenden Bloecken:

### 4.1 Prompt-Bloecke

```
System Prompt Assembly
  ├─> Role Definition
  │     "You are an AI coding assistant, powered by [model]. You operate in Cursor."
  │     "You are pair programming with a USER to solve their coding task."
  │
  ├─> <communication>
  │     Markdown-Formatierung, Code-Citations, Math-Notation
  │
  ├─> <tool_calling>
  │     Regeln fuer Tool-Nutzung: Nicht Tool-Namen erwaehnen, Standard-Format nutzen
  │
  ├─> <maximize_parallel_tool_calls>
  │     Unabhaengige Tool-Calls parallel ausfuehren
  │
  ├─> <maximize_context_understanding>
  │     Gruendliche Exploration, Symbol-Tracing, Semantic Search Strategie
  │
  ├─> <making_code_changes>
  │     Read before Edit, Dependency Files, Linter-Fixes
  │
  ├─> <citing_code>
  │     CODE REFERENCES (startLine:endLine:filepath) vs MARKDOWN CODE BLOCKS
  │
  ├─> <task_management>
  │     todo_write Tool fuer komplexe Tasks
  │
  ├─> Workspace Rules (.cursor/rules/)
  │     Projekt-spezifische Coding-Konventionen
  │
  ├─> User Rules
  │     Benutzerdefinierte Praeferenzen
  │
  └─> MCP Instructions
        Konfigurierte MCP-Server und deren Nutzungshinweise
```

### 4.2 Mode-spezifische Anpassungen

Der System Prompt wird je nach aktivem Mode modifiziert:

| Mode | Zusatz-Instruktionen |
|---|---|
| **Agent** | Volle Tool-Palette, Edit-Berechtigung, Terminal-Zugang |
| **Plan** | Read-Only Reminder, `create_plan` Tool verfuegbar, keine Edits |
| **Ask** | Read-Only, eingeschraenkte Tools, Erklaer-Fokus |
| **Debug** | Hypothesen-getriebene Analyse, Log-Instrumentierung |

---

## 5. Tool-System

Cursor stellt dem LLM 15+ spezialisierte Tools zur Verfuegung, definiert im OpenAI Function Calling Format.

### 5.1 Tool-Kategorien

**Code-Verstaendnis**:
- `codebase_search` / `SemanticSearch` - Semantische Suche nach Bedeutung
- `grep` / `Grep` - Exakte Text/Regex-Suche (basiert auf ripgrep)
- `read_file` / `Read` - Dateien lesen mit optionalem Offset/Limit
- `glob_file_search` / `Glob` - Dateien nach Muster finden
- `list_dir` - Verzeichnisinhalt auflisten

**Code-Aenderung**:
- `edit_file` - Intelligentes Code-Editing mit `// ... existing code ...` Markern
- `StrReplace` - Exakte String-Ersetzungen
- `Write` - Neue Dateien erstellen / ueberschreiben
- `delete_file` / `Delete` - Dateien loeschen
- `edit_notebook` / `EditNotebook` - Jupyter Notebook Zellen bearbeiten

**Ausfuehrung**:
- `run_terminal_cmd` / `Shell` - Sandboxed Terminal-Kommandos
- `web_search` / `WebSearch` - Web-Recherche
- `WebFetch` - URL-Inhalte abrufen

**Projekt-Management**:
- `todo_write` / `TodoWrite` - Task-Tracking mit Status
- `create_plan` - Strukturierte Planungsdokumente

**Linting**:
- `read_lints` / `ReadLints` - Linter-Fehler auslesen

**Subagenten**:
- `Task` - Spezialisierte Sub-Agenten starten (generalPurpose, explore, browser-use)
- `SwitchMode` - Modus wechseln

### 5.2 Tool-Definition Format

Jedes Tool wird als OpenAI Function Definition spezifiziert:

```json
{
  "type": "function",
  "function": {
    "name": "codebase_search",
    "description": "semantic search that finds code by meaning...",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "A complete question about what you want to understand"
        },
        "target_directories": {
          "type": "array",
          "items": { "type": "string" }
        },
        "explanation": {
          "type": "string",
          "description": "Why this tool is being used"
        }
      },
      "required": ["query", "target_directories", "explanation"]
    }
  }
}
```

### 5.3 Tool-Aufruf und Antwort-Zyklus

```
LLM generiert Tool-Call
  ↓
{
  "tool_calls": [{
    "id": "call_abc123",
    "type": "function",
    "function": {
      "name": "read_file",
      "arguments": "{\"target_file\": \"src/main.py\"}"
    }
  }]
}
  ↓
Client fuehrt Tool aus (lokal)
  ↓
Tool-Result wird als neue Message eingefuegt
  ↓
{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "1|import os\n2|import sys\n..."
}
  ↓
Naechster LLM-Turn mit Tool-Result im Kontext
  ↓
LLM generiert Text-Antwort oder weitere Tool-Calls
```

### 5.4 Parallele Tool-Ausfuehrung

Cursor optimiert auf parallele Tool-Calls. Wenn keine Abhaengigkeiten bestehen, werden mehrere Tools gleichzeitig aufgerufen:

```
Beispiel: "Fuege Authentication hinzu"
  ↓
Parallel:
  ├─> codebase_search("How does authentication work?")
  ├─> grep("auth|login|session")
  ├─> read_file("src/app.py")
  └─> web_search("best practices authentication 2026")
        ↓
Sequential (abhaengig von Ergebnissen):
  ├─> read_file("src/middleware/auth.py")  [gefunden durch search]
  └─> edit_file("src/routes/login.py")    [basierend auf Kontext]
```

---

## 6. Codebase-Indexierung und RAG

### 6.1 Indexierungs-Pipeline

```
Projekt oeffnen
  ↓
Background Scanning
  ├─> Dateien in Chunks aufteilen (tree-sitter fuer AST-basiertes Splitting)
  ├─> Chunks: ~einige hundert Tokens, an logischen Grenzen (Funktionen, Klassen)
  └─> .gitignore / .cursorignore respektieren
        ↓
Embedding-Berechnung
  ├─> OpenAI Embedding Model oder Custom Model
  └─> Vektor-Repraesentation des semantischen Inhalts
        ↓
Vektor-Datenbank (Backend)
  ├─> Embeddings mit Metadaten (Datei, Zeilen, Chunk-ID)
  └─> Nearest-Neighbor-Suche fuer Queries
```

### 6.2 Retrieval-Augmented Generation (RAG)

```
User-Query
  ↓
Query → Embedding-Vektor
  ↓
Nearest-Neighbor-Suche in Vektor-DB
  ↓
Top-K relevante Code-Chunks
  ├─> Dateiname + Zeilennummern
  └─> Code-Inhalt
        ↓
In LLM-Prompt eingebettet als Kontext
  ↓
LLM generiert Antwort basierend auf Projekt-Kontext
```

---

## 7. Shadow Workspace

Cursor implementiert ein **Shadow Workspace** Konzept: ein verstecktes Electron-Fenster, das das Projekt spiegelt.

**Zweck**:
- AI-generierte Code-Aenderungen sicher testen bevor sie dem User praesentiert werden
- Language Server Feedback (Type-Checking, Linting) auf vorgeschlagene Aenderungen anwenden
- Selbst-Verbesserungsschleife: Fehler werden zurueck an das LLM gegeben

**Ablauf**:
```
AI generiert Code-Aenderung
  ↓
Shadow Workspace (verstecktes Fenster)
  ├─> Aenderungen anwenden (nicht in echten Dateien)
  ├─> Language Server pruefen (TypeScript, Python, etc.)
  └─> Diagnostics sammeln
        ↓
[Wenn Fehler] → Feedback an LLM → Neuer Versuch
[Wenn OK]     → Aenderung dem User praesentieren
```

---

## 8. Subagenten-Architektur

Seit Januar 2026 unterstuetzt Cursor das Starten spezialisierter Subagenten:

### 8.1 Subagent-Typen

| Typ | Zweck | Faehigkeiten |
|---|---|---|
| `generalPurpose` | Komplexe, mehrstufige Tasks | Voller Tool-Zugang, Code-Suche, Ausfuehrung |
| `explore` | Schnelle Codebase-Exploration | Glob, Grep, Read - optimiert fuer Geschwindigkeit |
| `browser-use` | Browser-basiertes Testing | Navigation, Interaktion, Screenshots |

### 8.2 Subagent-Kommunikation

```
Parent Agent
  ├─> Task(prompt="...", subagent_type="explore")
  │     ├─> Subagent erhaelt eigenen Kontext
  │     ├─> Subagent fuehrt Tools aus
  │     └─> Subagent gibt Ergebnis zurueck (einzelne Message)
  │
  └─> Bis zu 4 Subagenten parallel
```

**Wichtig**: Subagenten haben keinen Zugriff auf den Chat-Verlauf des Parent-Agenten. Der Prompt muss alle noetige Information enthalten.

---

## 9. Background Agent API

Cursor bietet seit 2026 eine **Background Agent API** fuer programmatischen Zugriff:

### 9.1 Authentifizierung

Ueber `WorkosCursorSessionToken` (Cookie/Environment Variable)

### 9.2 Endpunkte

| Endpunkt | Methode | Beschreibung |
|---|---|---|
| Composer erstellen | POST | Neuen Background Composer mit Task-Beschreibung starten |
| Composer auflisten | GET | Alle laufenden Background Composer abrufen |
| Composer Details | GET | Status und Details eines spezifischen Composers |
| Settings | GET | User-Einstellungen abrufen |

### 9.3 Programmatischer Zugriff (TypeScript)

```typescript
import { CursorAPIClient } from 'cursor-api-client';

const client = new CursorAPIClient('session-token');

const result = await client.createBackgroundComposer({
  taskDescription: 'Add user authentication',
  repositoryUrl: 'https://github.com/user/repo.git',
  branch: 'main',
  model: 'claude-4-sonnet-thinking'
});

const composers = await client.listComposers();
```

### 9.4 Direkter RPC-Zugriff (Go)

```go
creds, _ := cursor.GetDefaultCredentials()
aiService := cursor.NewAiServiceClient()

model := "gpt-4"
resp, _ := aiService.StreamChat(context.TODO(), cursor.NewRequest(creds, &aiserverv1.GetChatRequest{
    ModelDetails: &aiserverv1.ModelDetails{
        ModelName: &model,
    },
    Conversation: []*aiserverv1.ConversationMessage{
        {
            Text: "Hello, who are you?",
            Type: aiserverv1.ConversationMessage_MESSAGE_TYPE_HUMAN,
        },
    },
}))

for resp.Receive() {
    next := resp.Msg()
    fmt.Printf(next.Text)
}
```

---

## 10. Model-Routing

Cursor verwendet verschiedene Modelle je nach Aufgabentyp:

| Aufgabe | Modell-Typ | Beispiele |
|---|---|---|
| Chat / komplexe Analyse | Frontier LLM | Claude 4.6 Opus, GPT-5.2/5.3, Gemini 3 Pro |
| Tab Completion | Custom Fast Model | "Copilot++" (basierend auf Llama 70B) |
| Fast Apply (Diffs) | Spezialisiertes Fine-Tuned Model | Optimiert fuer Code-Diffs, >1000 Tokens/s |
| Embeddings | Embedding Model | OpenAI Embedding oder Custom |

**Speculative Decoding**: Ein kleineres "Draft"-Modell generiert mehrere Token voraus, die das Hauptmodell parallel verifiziert → signifikant schnellere Inferenz.

---

## 11. Sicherheitsmodell

### 11.1 Terminal Sandbox

Kommandos laufen standardmaessig in einer Sandbox:
- Erlaubt: Schreiben im Workspace, Lesen im Dateisystem
- Blockiert: Netzwerk, Git-Write, ignorierte Dateien, USB
- Erweiterbar: `network`, `git_write`, `all` Permissions

### 11.2 Privacy Mode

- Wenn aktiviert: Kein Code wird nach Erfuellung des Requests gespeichert
- Wenn deaktiviert: Anonymisierte Telemetrie, kein langfristiges Code-Speichern

### 11.3 Rules System

- `.cursor/rules/` - Projekt-spezifische AI-Verhaltensregeln
- User Rules - Globale Praeferenzen
- `<system_reminder>` Tags - Dynamische Instruktionen (nie sichtbar fuer User)

---

## Quellen und Referenzen

- Cursor Offizielle Dokumentation: https://docs.cursor.com
- Cursor Blog - Plan Mode: https://cursor.com/blog/plan-mode
- Cursor Blog - Dynamic Context Discovery: https://cursor.com/blog/dynamic-context-discovery
- Cursor Blog - Codex Model Harness: https://cursor.com/blog/codex-model-harness
- Reverse-Engineered RPC Client: https://github.com/everestmz/cursor-rpc
- Background Agent API Client: https://github.com/mjdierkes/cursor-background-agent-api
- Architecture Analysis: https://adityarohilla.com/2025/05/08/how-cursor-works-internally/
- System Prompt Analysis: https://medium.com/@lakkannawalikar/cursor-ai-architecture-system-prompts-and-tools-deep-dive-77f44cb1c6b0