Cursor vs Claude Code: Running Both in CompozyOS

If you already use Cursor or Claude Code, trying CompozyOS does not require moving your project to a new agent implementation. You select a provider, create a session, and send a prompt. CompozyOS keeps the session history and manages execution around the selected agent.

The integration has a detail worth understanding before you configure it: Cursor Agent has an ACP entry point; the Claude Code integration uses an ACP adapter built on the Claude Agent SDK. The two launch paths differ even though CompozyOS presents them through the same session commands. See Cursor's ACP documentation and the Claude Agent ACP adapter.

This is a setup comparison from the CompozyOS project, checked against its implementation and the linked upstream documentation on September 11, 2026. It does not rank coding quality, speed, or cost.

Compare the integration you will actually run

Here, “Cursor” means the Cursor Agent CLI. Opening the Cursor editor does not launch a provider inside a CompozyOS session.

These values come from the CompozyOS provider registry. Local configuration can override them; provider inspection shows the effective setup on your machine.

Choose the provider whose account and CLI you already use for the first walkthrough. Once that works, testing the second provider becomes a small configuration change with an understandable failure boundary. An authentication failure then points at the provider setup, while a session creation failure points at the CompozyOS definition or workspace.

Prepare the runtime and provider login

Install CompozyOS using the installation guide. The CLI path on a supported macOS or Linux host is:

curl -fsSL https://compozy.com/install.sh | sh
compozy install
compozy daemon start
compozy version
compozy config validate

The installer downloads the distribution; compozy install bootstraps its home and configuration. It can update existing bootstrap configuration, so this walkthrough assumes a fresh installation or an installation whose setup you intend to review. Existing agent files are preserved.

For the Claude integration, make sure Node.js and npx are available to the daemon, and complete the provider login:

compozy provider auth login claude
compozy provider inspect claude -o json

For Cursor, install and authenticate its Agent CLI using Cursor's CLI setup. Confirm the executable that CompozyOS expects is available:

command -v cursor-agent
compozy provider inspect cursor -o json

Both built-ins use native_cli authentication: CompozyOS does not require a separate API key preflight for them. The provider still needs working credentials, and model use remains subject to that provider's account and billing. A local CompozyOS daemon does not imply local inference.

Define an agent without changing your existing general agent

From the repository you want to use, create .compozy/agents/provider-check/AGENT.md with this content. The directory name and the frontmatter name must match:

---
name: provider-check
provider: claude
permissions: approve-reads
---
 
Explain this repository's structure using file paths as evidence.
Read the relevant files before drawing conclusions.
Ask before making changes or running commands that need approval.

The Markdown body is required. permissions: approve-reads selects the daemon policy; the final sentence explains the desired behavior to the model. Those are separate mechanisms. For the permission boundary and its limits, read the autonomous coding setup.

To make Cursor the definition's default, change only provider: claude to provider: cursor. Leave model absent for this initial check. A model name copied from an older article may no longer be a valid choice for the installed provider.

Create first, bind on the first prompt

Run these commands from the repository root:

compozy session new --cwd "$PWD" --agent provider-check --name provider-check
compozy session list -o json

Creation should return an active logical session with an unbound runtime. That distinction lets you verify workspace and definition resolution before spending a model turn. The following is a schematic of the lifecycle, not captured command output:

session new
    -> active session, stable ID, runtime unbound
session prompt
    -> provider selection, ACP launch, model turn
session history / recap
    -> reads of the retained session record

Copy the returned ID. In the next examples, replace sess_1234 with that ID. Choose one of these first-prompt commands:

compozy session prompt sess_1234 \
  "Map the repository's main modules and cite their entry files." \
  --provider claude

compozy session prompt sess_1234 \
  "Map the repository's main modules and cite their entry files." \
  --provider cursor

The explicit provider belongs to this prompt's runtime selection. It does not rewrite AGENT.md. Later prompts can select another runtime, but that is a process transition, not a guarantee that every provider-specific behavior or conversation feature transfers identically.

Inspect what happened:

compozy session status sess_1234 -o json
compozy session history sess_1234
compozy session recap sess_1234

Use compozy session events sess_1234 --follow when you want a live event stream; it keeps running until you stop following it. History and recap are bounded reads suited to checking a finished turn.

Diagnose model selection separately

If the default works and you need a specific model, refresh the relevant catalog:

compozy provider models list claude --refresh -o json
compozy provider models list cursor --refresh -o json

Cursor discovery may start a short ACP inspection process. CompozyOS requires an explicit Cursor model to match fresh advertised values; human-friendly aliases from another CLI command are not necessarily accepted identifiers. A stale catalog is useful diagnostic context, not proof that a model can be selected now. The model catalog guide describes freshness and source precedence.

If a launch fails, first check the executable, login, effective provider configuration, and model selection. Repeatedly creating sessions will not repair any of those prerequisites.

Compare the results on the same repository

For a meaningful local comparison, create a separate session for each provider at the same Git revision. Use the same prompt and permission mode. Record the selected model, the files each answer cites, any incorrect claims, and the approvals needed. Do not let the first agent's edits become the second agent's starting point.

That exercise answers whether the provider fits your work. CompozyOS gives both attempts the same place to inspect their history, but a shared protocol does not make their answers equivalent. Continue with agents, sessions, and optional souls when you want reusable definitions for those different working styles.