Go Cursor SDK

简体中文 | English

A full-featured Go SDK for reading and parsing all local data from Cursor IDE, including session records, Composer data, AI statistics, user configurations, and more.

Features

Core Features

• 🔍 Unified Client: CursorClient provides a unified access point
• 📝 Session Management: Read and parse AI conversation session records
• 🎨 Composer Data: Access Composer sessions and code modification statistics
• 📊 Statistics Data: Get daily statistics and acceptance rates for AI code generation
• ⚙️ Configuration Access: Read user configurations and personal context
• 🗂️ Workspace Data: Access workspace-specific data
• 💻 Terminal History: Read terminal command and directory history (with search and time filtering)
• 🔌 MCP Service: Read MCP (Model Context Protocol) server information (supports user and system servers)
• 🎨 Agent Layout: Read Cursor Agent layout configuration (including panel, sidebar, and other layout states)

Advanced Features

• 🔎 Flexible Queries: QueryBuilder supports complex query conditions
• 💾 Data Export: Support export to JSON, CSV, and other formats
• ⚡ Performance Optimization: Built-in caching mechanism with concurrent access support
• 🔒 Secure Access: Read-only mode, does not modify any data
• 🌍 Cross-Platform: Supports Windows, macOS, Linux

Project Structure

This project follows the Golang Standard Project Layout, with clear code organization and easy maintenance:

go-cursor-sdk/
├── cmd/                    # Command-line tools
│   └── test_local/        # Local testing tool
├── example/               # Example code
├── internal/              # Internal implementation (not importable by external projects)
│   ├── parser/           # Data parsers
│   └── locator/          # Storage locators
├── *.go                   # Public API (root directory)
└── *_test.go             # Test files

Public API vs Internal Implementation

• Public API (root directory): All interfaces and types that can be used externally

  • client.go - Unified client
  • *_reader.go - Various data readers
  • models.go - Data models
  • query_builder.go - Query builder
  • exporter.go - Data exporter
  • cache.go - Cache management
  • watcher.go - Data watcher
  • errors.go - Error types
  • logger.go - Logger interface

• Internal Implementation (internal/ directory): Implementation details that should not be depended on by external projects

  • internal/parser/ - Data parsing logic
  • internal/locator/ - Storage path location logic

This design ensures:

1. Backward Compatibility: Public API remains stable while internal implementation can be freely refactored
2. Clear Separation of Concerns: Public interfaces are clearly separated from implementation details
3. Better Maintainability: Internal code can be freely modified without affecting users

Installation

go get github.com/vibe-coding-labs/go-cursor-sdk

Quick Start

Using the Unified Client

package main

import (
    "fmt"
    "log"
    "time"
    
    cursor "github.com/vibe-coding-labs/go-cursor-sdk"
)

func main() {
    // Create unified client
    config := &cursor.ClientConfig{
        EnableCache: true,
        CacheTTL:    5 * time.Minute,
        LogLevel:    cursor.LogLevelInfo,
    }
    
    client, err := cursor.NewCursorClient(config)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()
    
    // Access session data
    sessions, err := client.Sessions().ListSessions()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Found %d sessions\n", len(sessions))
    for _, session := range sessions {
        fmt.Printf("Session: %s, Messages: %d\n", session.Title, len(session.Messages))
    }
    
    // Access Composer data
    composers, err := client.Composers().ListComposers()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Found %d Composers\n", len(composers))
    
    // Access statistics data
    stats, err := client.Stats().GetStatsRange(
        time.Now().AddDate(0, 0, -7),
        time.Now(),
    )
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Statistics for the last 7 days: %d entries\n", len(stats))
    
    // Access MCP service data
    mcpData, err := client.MCPService().GetMCPServiceData()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Total MCP servers: %d\n", mcpData.TotalCount)
    fmt.Printf("User servers: %d\n", len(mcpData.Servers))
    
    // Access terminal history
    history, err := client.TerminalHistory().GetHistory()
    if err != nil {
        log.Fatal(err)
    }
    
    if history.Commands != nil {
        fmt.Printf("Command history: %d entries\n", len(history.Commands.Entries))
    }
    
    // Access Agent layout configuration
    layout, err := client.AgentLayout().GetAgentLayout()
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Editor width: %d, Sidebar visible: %v\n", layout.EditorWidth, layout.SidebarVisible)
}

Using Query Builder

// Build complex queries
query := cursor.NewQueryBuilder().
    TimeRange(startTime, endTime).
    Keyword("bug fix").
    Limit(10).
    SortBy("created_at", "desc").
    Build()

// Query sessions
sessions, err := client.Sessions().QuerySessions(query)
if err != nil {
    log.Fatal(err)
}

Exporting Data

// Export sessions as JSON
err := client.Export().ExportSessionsJSON(sessions, "sessions.json")
if err != nil {
    log.Fatal(err)
}

// Export statistics as CSV
err = client.Export().ExportStatsCSV(stats, "stats.csv")
if err != nil {
    log.Fatal(err)
}

// Batch export all data
err = client.Export().ExportAll("./export", client)
if err != nil {
    log.Fatal(err)
}

Watching Data Changes

// Create client with Watcher enabled
config := &cursor.ClientConfig{
    EnableWatcher: true,
    LogLevel:      cursor.LogLevelInfo,
}

client, err := cursor.NewCursorClient(config)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Get Watcher
watcher := client.Watcher()

// Watch session changes
watcher.WatchSessions(func(event cursor.WatchEvent) {
    fmt.Printf("Session event: %s - %s\n", event.Type, event.Action)
})

// Watch Composer changes
watcher.WatchComposers(func(event cursor.WatchEvent) {
    fmt.Printf("Composer event: %s - %s\n", event.Type, event.Action)
})

// Start watching
if err := watcher.Start(); err != nil {
    log.Fatal(err)
}

// ... application running ...

// Stop watching
watcher.Stop()

API Reference

For complete API documentation, please refer to:

• API Interface List - Complete list of all interfaces
• API Documentation - Detailed usage examples
• Data Models - Data structure definitions
• Complete Examples - Practical usage examples

Examples

More examples can be found in the example directory.

License

MIT License