automaker/docs/cursor-integration-analysis.md

Cursor CLI Integration Analysis

Phase 0 Analysis Document for AutoMaker Cursor Integration Generated: 2025-12-28

Executive Summary

This document analyzes the existing Claude CLI integration architecture in AutoMaker and documents the Cursor CLI (cursor-agent) behavior to plan a parallel provider implementation.

1. Current Architecture Analysis

1.1 Provider System (apps/server/src/providers/)

BaseProvider (base-provider.ts)

• Abstract class with core interface for all providers
• Key methods:
  • execute(options) - Runs the CLI process
  • buildCommand(options) - Constructs CLI command
  • parseOutput(output) - Parses CLI response
  • buildSystemPrompt(options) - Constructs system prompts
• Uses @automaker/platform.spawnJSONLProcess() for CLI execution
• Handles abort signals for cancellation

ClaudeProvider (claude-provider.ts)

• Extends BaseProvider for Claude CLI
• Uses Claude Agent SDK via @anthropic-ai/claude-code package
• Key features:
  • Thinking levels (none, low, medium, high, ultrathink)
  • Model selection (haiku, sonnet, opus)
  • System prompt injection
  • Session/conversation management
  • MCP server support
• SDK options built via buildSdkOptions() in sdk-options.ts

ProviderFactory (provider-factory.ts)

• Creates provider instances based on type
• Currently only supports 'claude' provider
• Extension point for adding new providers

Types (types.ts)

• ProviderType: Currently 'claude'
• ProviderConfig: Configuration for providers
• ExecuteResult: Standardized result format

1.2 Service Integration

AgentService (agent-service.ts)

• Manages chat agent sessions
• Uses ClaudeProvider for execution
• Handles streaming output to clients
• Session persistence and history

AutoModeService (auto-mode-service.ts)

• Orchestrates feature generation workflow
• Manages concurrent feature execution
• Uses provider for each feature task
• Handles planning, execution, verification phases

SDK Options (sdk-options.ts)

• Builds Claude SDK options from settings
• Handles thinking level configuration
• Maps model aliases to full model IDs
• Configures MCP servers

1.3 UI Components

LogParser (log-parser.ts)

• Parses agent output into structured entries
• Detects entry types: tool_call, tool_result, phase, error, success, etc.
• Extracts metadata: tool name, file path, summary
• Claude-specific patterns (🔧 Tool:, etc.)

LogViewer (log-viewer.tsx)

• Renders parsed log entries
• Collapsible sections
• Filtering by type/category
• Tool-specific icons and colors

1.4 Setup Flow

Claude Status Detection (get-claude-status.ts)

• Checks CLI installation via which/where
• Searches common installation paths
• Detects authentication via:
  • ~/.claude/stats-cache.json (activity)
  • ~/.claude/.credentials.json (OAuth)
  • Environment variables (ANTHROPIC_API_KEY)
  • Stored API keys in AutoMaker

Setup View (setup-view.tsx)

• Multi-step wizard: welcome → theme → claude → github → complete
• ClaudeSetupStep handles CLI detection and auth
• Skip option for users without Claude

HTTP API Client (http-api-client.ts)

• Client-side API wrapper
• setup.getClaudeStatus() - Get Claude CLI status
• setup.installClaude() - Trigger installation
• setup.authClaude() - Trigger authentication

1.5 Types Package (@automaker/types)

Model Types (model.ts)

CLAUDE_MODEL_MAP = {
  haiku: 'claude-haiku-4-5-20251001',
  sonnet: 'claude-sonnet-4-5-20250929',
  opus: 'claude-opus-4-5-20251101',
};

Settings Types (settings.ts)

• ModelProvider: Currently 'claude' only
• AIProfile: Provider field for profiles
• ThinkingLevel: Reasoning intensity levels

Model Display (model-display.ts)

• CLAUDE_MODELS: UI metadata for model selection
• getModelDisplayName(): Human-readable names

2. Cursor CLI Behavior Analysis

2.1 Installation & Location

• Binary: cursor-agent
• Installed at: ~/.local/bin/cursor-agent
• Version tested: 2025.12.17-996666f
• Config directory: ~/.cursor/
• Config file: ~/.cursor/cli-config.json

2.2 Authentication

# Login command
cursor-agent login

# Status check
cursor-agent status    # or `cursor-agent whoami`

# Logout
cursor-agent logout

Authentication is browser-based (OAuth) by default. Status output:

✓ Logged in as user@example.com

2.3 CLI Options

Option	Description
--print	Non-interactive mode, outputs to stdout
--output-format <format>	text, json, or stream-json
--model <model>	Model selection (e.g., gpt-5, sonnet-4)
--workspace <path>	Working directory
--resume [chatId]	Resume previous session
--api-key <key>	API key (or CURSOR_API_KEY env)
--force	Auto-approve tool calls
--approve-mcps	Auto-approve MCP servers

2.4 Output Formats

JSON Format (--output-format json)

Single JSON object on completion:

{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 2691,
  "result": "Response text here",
  "session_id": "uuid",
  "request_id": "uuid"
}

Stream-JSON Format (--output-format stream-json)

JSONL (one JSON per line) during execution:

1. Init event:

{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "login",
  "cwd": "/path",
  "session_id": "uuid",
  "model": "Composer 1"
}

2. User message:

{
  "type": "user",
  "message": { "role": "user", "content": [{ "type": "text", "text": "prompt" }] },
  "session_id": "uuid"
}

3. Thinking events:

{"type":"thinking","subtype":"delta","text":"","session_id":"uuid","timestamp_ms":123}
{"type":"thinking","subtype":"completed","session_id":"uuid","timestamp_ms":123}

4. Assistant response:

{
  "type": "assistant",
  "message": { "role": "assistant", "content": [{ "type": "text", "text": "response" }] },
  "session_id": "uuid"
}

5. Result:

{
  "type": "result",
  "subtype": "success",
  "duration_ms": 1825,
  "is_error": false,
  "result": "response",
  "session_id": "uuid"
}

2.5 Config File Structure

~/.cursor/cli-config.json:

{
  "permissions": {
    "allow": ["Shell(ls)"],
    "deny": []
  },
  "version": 1,
  "model": {
    "modelId": "composer-1",
    "displayModelId": "composer-1",
    "displayName": "Composer 1"
  },
  "approvalMode": "allowlist",
  "sandbox": {
    "mode": "disabled",
    "networkAccess": "allowlist"
  }
}

2.6 Available Models

From --help:

• gpt-5
• sonnet-4
• sonnet-4-thinking
• composer-1 (default)

2.7 MCP Support

cursor-agent mcp list          # List configured servers
cursor-agent mcp login <id>    # Authenticate with server
cursor-agent mcp list-tools <id>  # List tools for server
cursor-agent mcp disable <id>  # Remove from approved list

3. Integration Strategy

3.1 Types to Add (@automaker/types)

// settings.ts
export type ModelProvider = 'claude' | 'cursor';

// model.ts (new: cursor-models.ts)
export type CursorModelId = 'composer-1' | 'gpt-5' | 'sonnet-4' | 'sonnet-4-thinking';

export const CURSOR_MODEL_MAP: Record<string, CursorModelId> = {
  composer: 'composer-1',
  gpt5: 'gpt-5',
  sonnet: 'sonnet-4',
  'sonnet-thinking': 'sonnet-4-thinking',
};

3.2 Provider Implementation

New CursorProvider class extending BaseProvider:

• Override buildCommand() for cursor-agent CLI
• Override parseOutput() for Cursor's JSONL format
• Handle stream-json output parsing
• Map thinking events to existing log format

3.3 Setup Flow Changes

1. Add CursorSetupStep component
2. Add get-cursor-status.ts route handler
3. Update setup wizard to detect/choose providers
4. Add Cursor authentication flow

3.4 UI Updates

1. Extend LogParser for Cursor event types
2. Add Cursor icon (Terminal from lucide-react)
3. Update model selectors for Cursor models
4. Provider toggle in settings

4. Key Differences: Claude vs Cursor

Aspect	Claude CLI	Cursor CLI
Binary	claude	cursor-agent
SDK	@anthropic-ai/claude-code	Direct CLI spawn
Config dir	~/.claude/	~/.cursor/
Auth file	.credentials.json	cli-config.json
Output	SDK events	JSONL stream
Thinking	Extended thinking API	thinking events
Models	haiku/sonnet/opus	composer/gpt-5/sonnet-4
Session	Conversation system	session_id in output

5. Files to Create/Modify

Phase 1: Types

• libs/types/src/cursor-models.ts - Cursor model definitions
• libs/types/src/settings.ts - Update ModelProvider type
• libs/types/src/index.ts - Export new types

Phase 2: Provider

• apps/server/src/providers/cursor-provider.ts - New provider
• apps/server/src/providers/provider-factory.ts - Add cursor
• apps/server/src/providers/types.ts - Update ProviderType

Phase 3: Setup

• apps/server/src/routes/setup/get-cursor-status.ts - Detection
• apps/server/src/routes/setup/routes/cursor-status.ts - Route
• apps/server/src/routes/setup/index.ts - Register route

Phase 4: UI

• apps/ui/src/components/views/setup-view/steps/CursorSetupStep.tsx
• apps/ui/src/lib/log-parser.ts - Cursor event parsing
• apps/ui/src/lib/http-api-client.ts - Add cursor endpoints

6. Verification Checklist

• Read all core provider files
• Read service integration files
• Read UI streaming/logging files
• Read setup flow files
• Read types package files
• Document Cursor CLI behavior
• Create this analysis document

7. Next Steps

Proceed to Phase 1: Types & Interfaces to:

1. Add Cursor model types to @automaker/types
2. Update ModelProvider type
3. Create cursor model display constants