Migrating from Cursor to OAC

Convert your .cursorrules to OpenAgents Control format and unlock Skills, Hooks, multi-agent support, and granular permissions.

Overview

Why migrate?

Feature	Cursor	OAC
Multiple agents	Single file only	Unlimited agents
Skills system	Not supported	Full support
Hooks	Not supported	Event-driven hooks
Permissions	Binary (on/off)	Granular (allow/deny/ask per path)
Contexts	Inline only	External context files

OAC provides a superset of Cursor's capabilities while maintaining backward compatibility.

Prerequisites

Required:

Node.js >= 18
npm or pnpm

Install the compatibility layer:

npm install @openagents-control/compatibility-layer

Quick Migration

One command conversion:

oac-compat convert .cursorrules -f oac -o agent.md

This reads your .cursorrules file and generates an OAC-compatible agent.md.

Verify the result:

oac-compat validate agent.md

Step-by-Step Manual Migration

1. Cursor Rules Structure

Cursor uses a single .cursorrules file in the project root. Two formats are supported:

Plain text format:

You are a senior TypeScript developer.
Always use strict mode.
Prefer functional programming patterns.
Write comprehensive tests for all code.

Frontmatter format (optional):

---
name: typescript-dev
description: TypeScript development assistant
model: gpt-4
temperature: 0.7
---

You are a senior TypeScript developer.
Always use strict mode.
Prefer functional programming patterns.
Write comprehensive tests for all code.

2. OAC Agent Structure

OAC agents use markdown with YAML frontmatter:

---
name: typescript-dev
description: TypeScript development assistant
mode: primary
model: gpt-4
temperature: 0.7
tools:
  read: true
  write: true
  edit: true
  bash: true
  grep: true
  glob: true
---

# TypeScript Developer

You are a senior TypeScript developer.

## Guidelines

- Always use strict mode
- Prefer functional programming patterns
- Write comprehensive tests for all code

## Skills

<!-- Skills can be loaded dynamically -->

## Contexts

<!-- External context files for domain knowledge -->

3. Key Differences

Aspect	Cursor	OAC
File format	`.cursorrules` (plain/YAML)	`.md` with YAML frontmatter
Location	Project root	`.opencode/agent/` directory
Multiple agents	Not supported	Full support
Tool config	Implicit or comma-separated	Explicit object with booleans
Permissions	Binary only	Granular rules per path
Context handling	Inline in prompt	External files with priority
Skills	Not supported	Dynamic skill loading
Hooks	Not supported	Event-driven lifecycle hooks

4. Feature Mapping

Cursor Feature	OAC Equivalent	Notes
`name`	`frontmatter.name`	Direct mapping
`description`	`frontmatter.description`	Direct mapping
`model: gpt-4`	`frontmatter.model: gpt-4`	Direct mapping
`model: claude-3-opus`	`frontmatter.model: claude-opus-3`	Model ID normalized
`model: claude-3-sonnet`	`frontmatter.model: claude-sonnet-3`	Model ID normalized
`model: claude-3-haiku`	`frontmatter.model: claude-haiku-3`	Model ID normalized
`temperature`	`frontmatter.temperature`	Direct mapping
`tools: "read, write"`	`tools: { read: true, write: true }`	Object format
Plain text body	`systemPrompt`	Becomes the agent prompt
(not available)	`frontmatter.mode`	Set to `primary` or `subagent`
(not available)	`frontmatter.skills`	Add skill references
(not available)	`frontmatter.hooks`	Add lifecycle hooks
(not available)	`frontmatter.permission`	Add granular permissions
(not available)	`contexts`	Add external context files

5. Common Patterns

Pattern 1: Basic Rules

Before (Cursor):

You are a helpful coding assistant.
Follow best practices for clean code.
Always explain your changes.

After (OAC):

---
name: code-assistant
description: Helpful coding assistant
mode: primary
---

# Code Assistant

You are a helpful coding assistant.

## Guidelines

- Follow best practices for clean code
- Always explain your changes

Pattern 2: Tool Configuration

Before (Cursor):

---
name: restricted-agent
tools: read, grep, glob
---

You can only read and search files.
Do not modify any files.

After (OAC):

---
name: restricted-agent
description: Read-only agent for code analysis
mode: primary
tools:
  read: true
  grep: true
  glob: true
  write: false
  edit: false
  bash: false
---

# Restricted Agent

You can only read and search files.

## Restrictions

- Read files: ALLOWED
- Search files: ALLOWED  
- Modify files: DENIED
- Execute commands: DENIED

Pattern 3: Model Configuration

Before (Cursor):

---
name: creative-writer
model: claude-3-opus
temperature: 0.9
---

Write creative and engaging documentation.

After (OAC):

---
name: creative-writer
description: Creative documentation writer
mode: primary
model: claude-opus-3
temperature: 0.9
tools:
  read: true
  write: true
  edit: true
---

# Creative Writer

Write creative and engaging documentation.

## Style Guidelines

- Use vivid language
- Include examples
- Make content accessible

Note: Claude model IDs are normalized (claude-3-opus → claude-opus-3).

Pattern 4: Adding OAC-Exclusive Features

After migrating, enhance your agent with OAC-exclusive features:

Add Skills:

---
name: full-stack-dev
description: Full-stack development assistant
mode: primary
skills:
  - context-manager
  - task-management
---

Add Hooks:

---
name: validated-writer
description: Writer with validation hooks
mode: primary
hooks:
  - event: PreToolUse
    matchers:
      - "write"
      - "edit"
    commands:
      - type: command
        command: "npm run lint:check"
---

Add Granular Permissions:

---
name: safe-modifier
description: Agent with path-based permissions
mode: primary
permission:
  write:
    "/src/**": allow
    "/tests/**": allow
    "/config/**": ask
    "/**": deny
---

Add Contexts:

---
name: context-aware
description: Agent with external context files
mode: primary
---

# Context-Aware Agent

<!-- Contexts loaded automatically -->

With context files in .opencode/context/:

.opencode/context/
├── core/
│   ├── architecture.md
│   └── conventions.md
└── domain/
    └── business-rules.md

6. Limitations

Features that don't exist in Cursor (gained during migration):

Feature	Cursor	OAC	Workaround
Multiple agents	Single file	Unlimited	Create separate agent files
Skills system	None	Full support	Inline skill content in prompt
Hooks	None	Event-driven	Manual validation steps
Granular permissions	Binary	Per-path rules	Document restrictions in prompt
External contexts	None	Priority-based	Inline context in prompt
Subagent mode	None	Delegation support	Use primary mode only
Max steps	None	Configurable	Not available in Cursor

7. Validation

Validate your migrated agent:

# Check OAC format validity
oac-compat validate agent.md

# Compare capabilities
oac-compat info --tool cursor
oac-compat info --tool oac

# Test round-trip conversion
oac-compat convert agent.md -f cursor -o .cursorrules.test

Programmatic validation:

import { loadAgent, validateAgent } from '@openagents-control/compatibility-layer';

const agent = await loadAgent('./agent.md');
const errors = validateAgent(agent);

if (errors.length === 0) {
  console.log('Agent is valid!');
} else {
  console.error('Validation errors:', errors);
}

Troubleshooting

Frontmatter not parsing

Symptom: Agent name shows as cursor-agent instead of your custom name.

Cause: Frontmatter must have exact format with --- delimiters.

Fix:

---
name: my-agent
---

Content here...

Not:

---
name: my-agent
Content here...

Model not recognized

Symptom: Model defaults to gpt-4.

Cause: Cursor model IDs differ from OAC.

Fix: Use OAC model IDs:

Cursor	OAC
`claude-3-opus`	`claude-opus-3`
`claude-3-sonnet`	`claude-sonnet-3`
`claude-3-haiku`	`claude-haiku-3`
`gpt-4`	`gpt-4`
`gpt-4-turbo`	`gpt-4-turbo`
`gpt-4o`	`gpt-4o`

Tools not working

Symptom: Agent can't use expected tools.

Cause: Tools must be explicitly enabled in OAC.

Fix: Add tools to frontmatter:

tools:
  read: true
  write: true
  edit: true
  bash: true
  grep: true
  glob: true

Content appears duplicated

Symptom: System prompt contains frontmatter text.

Cause: Frontmatter delimiters missing or malformed.

Fix: Ensure proper YAML frontmatter format:

---
name: agent-name
---

Content starts here (not in frontmatter).

Next Steps

OAC Agent Configuration - Deep dive into OAC format
Skills System - Learn to use dynamic skills
Hooks Reference - Event-driven automation
Multi-Agent Setup - Configure agent delegation
OAC → Cursor Migration - Reverse migration guide

cursor-to-oac.md 9.5 KB History Raw

Migrating from Cursor to OAC

Overview

Prerequisites

Quick Migration

Step-by-Step Manual Migration

1. Cursor Rules Structure

2. OAC Agent Structure

3. Key Differences

4. Feature Mapping

5. Common Patterns

Pattern 1: Basic Rules

Pattern 2: Tool Configuration

Pattern 3: Model Configuration

Pattern 4: Adding OAC-Exclusive Features

6. Limitations

7. Validation

Troubleshooting

Frontmatter not parsing

Model not recognized

Tools not working

Content appears duplicated

Next Steps

cursor-to-oac.md 9.5 KB

History Raw