Agent integrations

Cursor

Talk to Cursor's coding agent through its command-line tool over ACP, or through the Cursor Python SDK with an API key.

Setup

Install the Cursor CLI on the runtime host: curl https://cursor.com/install -fsS | bash. The setup wizard offers to run this for you.
Log it in with agent login, which opens a browser. Or set CURSOR_API_KEY to use the Python SDK instead.
Run sleeptalk and choose Cursor, or let your agent run sleeptalk host ensure --agent cursor.

The SDK path also needs the cursor extra. In Sleeptalk 0.1.0 it selects cursor-sdk==1.0.37:

In the same Python environment as Sleeptalk

python -m pip install 'sleeptalk[cursor]'

Protected SDK startup accepts the exact tested versions 1.0.29, 1.0.31, 1.0.32, and 1.0.37. It does not accept an arbitrary version range. See harness qualification for what was checked.

Which path runs

The cursor type picks a path when the call starts:

Condition	Path
`CURSOR_API_KEY` is set, or `runtime = "sdk"`	The Cursor Python SDK (`cursor`).
No key, or `runtime = "acp"`, or `type = "cursor_acp"`	The Cursor CLI (`agent`) over ACP (`cursor_acp`).

Sleeptalk finds the CLI on PATH or in ~/.local/bin as agent or cursor-agent. on_incompatible = "fail" stops instead of falling back to the other path. sleeptalk doctor prints which path was selected and why.

Connection and session

ACP runs the CLI as a subprocess with JSON-RPC and opens a new session in the workspace. The SDK runs a local Agent and Run through its bridge. An open editor window does not identify the voice session; gateway_session_id selects an existing session where the path supports it.

Event mapping

Upstream event	Sleeptalk handling	Caller experience
ACP `agent_message_chunk` / SDK `assistant`	Assistant text to the shared sentence streamer.	Spoken reply.
ACP `tool_call`, `tool_call_update` / SDK `tool_call`	Tool lifecycle events.	Tool activity.
ACP `session/request_permission`	`PermissionRequested`.	An explicit tool decision.
ACP question and plan extensions	Clarification or plan approval requests.	A question or approval for the caller.
SDK `task` and task-tool messages	Correlated `WorkerEvent`.	Worker updates, where tasks are allowed.

Permissions and sub-agents

`permission_mode`	ACP (CLI)	SDK
`auto` (used when the field is empty)	Approves each tool request once.	Runs without approval prompts.
`pending`	The caller decides each request.	Refused: the SDK has no approval callback.
`deny`	Requests are refused.	Isolated: built-in tools, MCP, and tasks are all off.

ACP permission answers follow the option's kind, so a "no" can never select an allow option.

With pending or deny, an API key, and a new session, the ACP path runs isolated: it confirms the selected model and offers only allow once or deny, because a persistent allow can write an allowlist. The isolated path refuses to start if the host or workspace has hook configuration: .cursor/hooks.json, .claude/settings.json, .claude/settings.local.json, or Cursor's machine-wide hooks.json. It does not edit those files.

Voice and interruption

Assistant text passes through the shared sentence streamer before speech. Tool activity follows your narration setting; a tool result is not read aloud in full.

ACP abort sends session/cancel. SDK abort cancels the active run when it supports cancellation. Neither path advertises steering.

Limits and troubleshooting

"Cursor CLI (agent) not found." Install it with the command above, or set CURSOR_API_KEY to use the SDK.
"Cursor CLI is installed but not logged in." Run agent login, then start again.
"Cursor SDK has no pending tool-approval callback." Use the CLI path for voice approvals, or deny on the SDK.
"Protected Cursor sessions require a workspace and host without Cursor or Claude hook configuration files." Use a workspace and host without those files. Do not delete your hook settings just to pass the check.
The protected SDK version is not verified. Install the cursor extra in the environment that runs Sleeptalk; the 0.1.0 fresh-install pin is 1.0.37. Keep protected sessions in deny mode.

Implementation: Cursor ACP, shared ACP client, Cursor SDK, runtime selection.