fitchmultz/pi-cursor-sdk

로컬 @cursor/sdk 에이전트 런타임 (agent runtime)을 통해 pi가 Cursor 모델을 사용할 수 있게 해주는 pi 프로바이더 확장 기능 (pi provider extension)입니다.

pi의 네이티브 모델 선택기 (model picker), SDK가 노출하는 사고 제어 (thinking controls), 세션 복구 (session restore), 컨텍스트 표시 (context display), 그리고 기본 푸터 UX를 유지하면서 pi 내부에서 Cursor의 모델 카탈로그 (model catalog)를 사용하고 싶다면 이 확장 기능을 사용하세요.

패키지 설치:

pi install npm:pi-cursor-sdk

또는 GitHub에서 설치:

pi install https://github.com/fitchmultz/pi-cursor-sdk

Cursor 모델로 pi 시작:

pi --model cursor/composer-2.5

pi에서 다음 명령어를 실행하세요:
/login

그 다음 Use an API key를 선택하고, Cursor를 선택한 뒤, 귀하의 Cursor SDK API 키를 붙여넣으세요.

만약 키 없이 pi가 시작되었다면, /login 실행 후 /cursor-refresh-models를 실행하여 pi를 재시작하지 않고도 전체 실시간 Cursor 모델 카탈로그를 새로고침할 수 있습니다. pi 내부에서 /model을 사용하여 다른 Cursor 모델을 선택할 수 있습니다.

Node.js 22.19 이상
pi 0.76.0 이상
/login을 통해 저장된 Cursor SDK API 키 (CURSOR_API_KEY로 사용 가능) 또는 pi의 --api-key로 전달된 키

글로벌 @cursor/sdk 설치는 필요하지 않습니다. 이 패키지는 정확히 @cursor/sdk@1.0.16에 의존하므로, 일반적인 패키지 설치를 통해 이 확장 기능이 빌드되고 테스트된 SDK 버전이 함께 설치됩니다. 이 패키지는 pi의 최소 버전을 0.76.0으로 선언하며 최대 피어 버전 (maximum peer version)은 지정하지 않았으므로, 이 확장 기능이 재배포되기 전에 pi를 업데이트한 사용자도 기존 확장 기능을 시도하는 데 제한을 받지 않습니다. 현재 검증 기준은 pi 0.78.0 및 Cursor SDK 1.0.16입니다. 이전 버전의 pi 또는 Cursor SDK 호환성 경로는 유지 관리되지 않습니다.

pi install npm:pi-cursor-sdk

대체 GitHub 설치:

pi install https://github.com/fitchmultz/pi-cursor-sdk

글로벌 pi 설정 대신 현재 프로젝트의 .pi/settings.json에 패키지를 기록하려면 -l을 사용하세요:

pi install -l npm:pi-cursor-sdk

이 리포지토리에서 개발하는 경우:

npm install
pi -e . --model cursor/composer-2.5

pi-cursor-sdk

Cursor SDK에 명시적인 API 키를 전달합니다. 이는 Cursor Agent CLI 로그인, Cursor Desktop 로그인, 또는 agent status에 표시되는 Cursor 구독/OAuth 상태를 재사용하지 않습니다.

Cursor Dashboard → Integrations에서 사용자 API 키를 사용하거나, Team settings에서 서비스 계정 API 키를 사용하세요. Team Admin API 키는 Cursor SDK에서 지원되지 않습니다. 그 다음 아래 방법 중 하나를 사용하여 키를 설정하십시오.

권장 설정:

pi --model cursor/composer-2.5

그 다음, pi 내부에서:

/login 명령어를 실행합니다.
Use an API key를 선택합니다.
Cursor를 선택합니다.
Cursor SDK API 키를 붙여넣습니다.
키는 pi의 네이티브 파일인 ~/.pi/agent/auth.json에 저장됩니다.

키 없이 pi가 시작된 경우에도, 폴백(fallback) Cursor 모델들이 여전히 등록되므로 /login 명령어를 사용할 수 있습니다. /login 이후에는 폴백 모델 실행 시 저장된 키를 사용할 수 있으며, /cursor-refresh-models를 통해 pi를 재시작하지 않고도 Cursor SDK로부터 발견된 전체 실시간 Cursor 모델 카탈로그를 새로고침할 수 있습니다.

참고: 만약 /login 실행 시 Cursor ✓ key in models.json이라고 표시되지만, Cursor 키를 저장하지 않았고 CURSOR_API_KEY가 설정되지 않은 상태라면, 해당 상태는 pi 인증 상태(auth-status)의 제한 사항입니다. Cursor 실행을 위해서는 실제 Cursor SDK API 키가 여전히 필요합니다.

환경 설정:

export CURSOR_API_KEY="your-key"
pi --model cursor/composer-2.5

원샷(One-shot) 설정:

pi --api-key "your-key" --model cursor/composer-2.5 --cursor-no-fast -p "Say ok only."

탐색(Discovery) 시 이 확장 기능에 대해 pi의 네이티브 해결 순서를 사용합니다: --api-key, ~/.pi/agent/auth.json에 저장된 cursor 키, 그 다음 CURSOR_API_KEY 순입니다.

매번 pi가 시작될 때마다 실시간 Cursor.models.list 네트워크 라운드 트립(round-trip)이 발생하는 것을 방지하기 위해, 탐색된 카탈로그는 ~/.pi/agent/cursor-sdk-model-list.json에 디스크 캐시로 저장됩니다 (권한 0600으로 작성되며, API 키 지문(fingerprint)을 키로 사용합니다 — 키 자체는 절대 저장되지 않습니다). 캐시 TTL(Time To Live) 내의 웜 스타트업(Warm startup)은 네트워크 호출을 건너뛰며, Cursor 턴이 필요할 때까지 @cursor/sdk 로딩을 방지합니다; /cursor-refresh-models

항상 캐시를 우회하고 라이브 카탈로그 (live catalog)를 새로 고칩니다. 새로 고침에 실패할 경우, 일반적인 번들 포함 폴백 (bundled fallback)보다 이전에 캐시된 카탈로그를 우선적으로 사용합니다.

# 밀리초 단위의 캐시 수명 (기본값 86400000 = 24시간).
PI_CURSOR_SDK_MODEL_CACHE_TTL_MS=3600000 pi --model cursor/composer-2.5
# 캐시를 비활성화하고 항상 라이브로 탐색합니다.
...

API 키를 ~/.pi/agent/cursor-sdk.json에 저장하지 마십시오. 해당 파일은 Cursor의 빠른 기본값 (fast defaults)과 같이 비밀 정보가 아닌 확장 프로그램 상태만을 위한 것입니다. PATH는 실행 파일 검색만을 위한 것이며 API 키를 포함해서는 안 됩니다.

Cursor 모델 목록 보기:

pi --list-models cursor

예상 동작:

유효한 키가 있는 경우, Cursor 모델이 cursor 프로바이더 (provider) 아래에 나타납니다. 만약 탐색 (discovery) 과정에서 인증을 할 수 없거나 Cursor에 도달할 수 없는 경우, pi는 여전히 폴백 (fallback) Cursor 모델을 보여줄 수 있습니다. /login을 통해 인증을 추가한 후에는, 폴백 모델 실행 시 저장된 키를 사용할 수 있으며, /cursor-refresh-models를 통해 라이브 카탈로그를 새로 고칠 수 있습니다.

스모크 테스트 (Smoke test):

pi --model cursor/composer-2.5 --cursor-no-fast --no-session --mode json \
-p "Reply exactly PI_CURSOR_MODEL_OK and nothing else."

예상 결과: 최종 어시스턴트 텍스트는 PI_CURSOR_MODEL_OK여야 합니다. 만약 인증이 누락되었거나 유효하지 않은 경우, pi는 /login, CURSOR_API_KEY, 또는 --api-key를 통해 Cursor SDK API 키를 설정하라고 안내해야 합니다.

/model을 사용하여 대화형으로 Cursor 모델을 선택하거나, 명령줄에서 모델을 전달할 수 있습니다:

pi --model cursor/composer-2.5
pi --model cursor/gpt-5.5@1m
pi --model cursor/gpt-5.5@272k
...

모델 ID 읽는 법:

cursor/...는 이 확장 프로그램에 의해 등록된 Cursor 프로바이더 (provider)입니다. @1m, @272k, @300k는 컨텍스트 윈도우 (context-window) 변형입니다. :medium, :high, :xhigh는 Cursor SDK가 pi 제어 가능한 사고 파라미터 (thinking parameter)를 노출하는 모델에 대한 pi 사고 수준 (thinking-level) 접미사입니다. 이는 Cursor.models.list()에 의해 반환되는 모호하지 않은 최신 스타일의 Cursor 별칭 (aliases)입니다.

대상 모델에 컨텍스트 변형(context variants)이 있는 경우 동일한 컨텍스트 접미사(context suffixes)를 사용하여 함께 등록됩니다. 여러 기본 모델(base models)이 공유하거나 기본 모델 ID와 충돌하는 별칭(aliases)은 SDK 해석(resolution) 및 표시되는 메타데이터가 달라질 수 있으므로 건너뜁니다.

pi 사고 제어(thinking controls) 예시:

pi --model cursor/gpt-5.5@1m:medium
pi --model cursor/gpt-5.5@272k:xhigh
pi --model cursor/gpt-5.5@1m --thinking medium

Cursor 전용 파라미터(parameters)는 pi 모델 ID에 인코딩되지 않습니다. Cursor의 context는 pi의 네이티브 contextWindow를 변경하기 때문에 pi에서 볼 수 있는 모델 변형(model variant)이 됩니다. Cursor의 fast 및 Cursor SDK 대화 모드(conversation mode)는 모델 정체성(model identity)이 아닌 확장 상태(extension state)입니다. 별칭 모델 ID는 여전히 fast 기본값과 같은 Cursor 전용 상태를 기반이 되는 Cursor 기본 모델과 공유합니다.

모든 Cursor SDK 모델은 사고가 가능한(thinking-capable) Cursor 모델로 취급되어야 합니다. pi --list-models의 thinking 열은 더 좁은 의미를 갖습니다. 이는 단지 pi가 해당 모델에 대해 Cursor SDK 사고 파라미터(thinking parameter)를 제어할 수 있음을 의미합니다.

Cursor가 reasoning, effort 또는 불리언(boolean) thinking 파라미터를 노출하는 모델의 경우, pi의 네이티브 사고 제어는 Cursor SDK 파라미터로 매핑됩니다:

thinking과 effort를 모두 사용하는 Claude 모델의 경우, pi의 thinking off는 thinking=false를 전송하고 effort를 생략합니다.

pi --list-models에서 thinking=no는 pi가 --thinking, 최종 :medium 모델 접미사 또는 shift+tab을 통해 모델의 사고 수준을 제어할 수 없음을 의미합니다. 이는 Cursor 모델이 사고를 할 수 없다는 의미가 아닙니다.

일부 Cursor SDK 모델은 확장이 설정할 수 있는 reasoning, effort 또는 thinking 파라미터를 노출하지 않습니다. Cursor 사고(thinking)는 여전히 모델에 의해 활성화/지원되며, Cursor는 여전히 사고 델타(thinking deltas)를 방출할 수 있습니다. 확장은 SDK가 이를 방출할 때 pi의 네이티브 사고 렌더링(thinking rendering)을 통해 해당 델타를 표면화합니다.

/cursor-fast를 사용하세요.

모델이 Cursor의 fast 파라미터를 지원할 때, 선택된 Cursor 모델에 대해 fast 모드를 영구적으로 토글(toggle)합니다.

Fast 설정은 Cursor 베이스 모델별로 기억되며 다음 위치에 저장됩니다:

pi.appendEntry()를 통한 현재 세션
~/.pi/agent/cursor-sdk.json에 전역적으로 저장

저장된 기본값을 변경하지 않고 단일 실행(one run) 동안에만 fast 모드를 강제로 켜거나 끕니다:

pi --model cursor/gpt-5.5@1m --cursor-fast -p "Say ok only"
pi --model cursor/composer-2.5 --cursor-no-fast -p "Say ok only"

Composer 2 및 Composer 2.5는 fast 모드가 기본값일 수 있습니다. 단발성(one-shot)으로 fast 모드를 사용하지 않는 Composer 실행을 원한다면 --cursor-no-fast를 사용하세요. 출력 모드 (-p)에서 --cursor-no-fast는 조용히 실행되며 ~/.pi/agent/cursor-sdk.json에 기록하지 않습니다.

대화형 모드(interactive mode)에서 푸터(footer)는 fast 모드가 활성화되었을 때만 fast를 표시하며, 기본값이 아닐 때만 cursor 모드를 표시합니다. Fast 모드와 plan 모드는 하나의 Cursor 상태 값을 공유하므로 서로를 덮어쓰지 않습니다:

cursor fast
cursor plan
cursor fast · plan

cursor fast가 보이지 않는다면 fast 모드가 꺼져 있는 것입니다. cursor plan이 보이지 않는다면 Cursor SDK 모드가 기본 agent 모드인 상태입니다.

Cursor SDK 대화 모드(conversation mode)는 Cursor 전용 확장 상태(extension state)입니다. 이는 pi 모델의 변형이 아니며, pi의 사고/추론(thinking/reasoning)도 아니고, Cursor의 fast 모드도 아니며, pi의 별도 읽기 전용 plan-mode 확장도 아닙니다.

기본 모드는 agent입니다. 특정 모드에서 단발성 실행을 시작하려면 다음과 같이 합니다:

pi --model cursor/composer-2.5 --cursor-mode agent
pi --model cursor/composer-2.5 --cursor-mode plan

대화형으로 세션 모드를 변경하려면 다음과 같이 합니다:

/cursor-mode agent
/cursor-mode plan
/cursor-mode

인자 없이 /cursor-mode를 입력하면 현재 모드와 사용법을 보고합니다. CLI 플래그는 세션에 유지되지 않으며, 슬래시 명령(slash-command)을 통한 변경 사항은 pi.appendEntry()를 통해 유지됩니다.

유지 관리자(Maintainers)는 Cursor 모델 세션에서 /cursor-tools를 실행하여 현재 브릿지 활성화 상태(bridge enablement), 부트스트랩 매니페스트 활성화 상태(bootstrap manifest enablement), 유효한 PI_CURSOR_SETTING_SOURCES, 그리고 호출 가능한 인터페이스 스냅샷(callable-surface snapshot, 호스트 도구 요약 및 현재 pi__*

names). Cursor dogfood 체크리스트를 참조하세요.

새로운 로컬 Cursor SDK 에이전트가 생성될 때, 확장 프로그램은 Agent.create({ mode })를 통해 모드 (mode)를 시드(seed)합니다.

또한 확장 프로그램은 모든 agent.send(..., { mode }) 호출 시 유효한 Cursor 모드를 전송하므로, 풀링된(pooled) SDK 에이전트가 재사용되는 경우에도 /cursor-mode 및 --cursor-mode가 신뢰할 수 있는 단일 원천 (source of truth)으로 유지됩니다.

Cursor SDK plan 모드는 계획 지향적인 출력(plan-oriented output)과 Cursor 할 일/계획 활동(todo/plan activity)을 생성할 수 있지만, 이러한 재생 카드(replay cards)는 표시 전용(display-only)으로 유지됩니다. 이들은 pi의 계획 모드(plan-mode) 확장, pi 할 일(todos), 또는 활성 도구 상태(active tool state)를 구동하지 않습니다.

최신 사용자 메시지에서 가져온 이미지는 Cursor로 전달됩니다. 과거의 이미지는 트랜스크립트(transcript)에서 제외되며 [image omitted from transcript] 플레이스홀더(placeholder)로만 나타나므로, 이전 이미지에 대한 후속 질문 시에는 이미지를 다시 첨부하거나 텍스트 설명을 포함해야 합니다. 확장 프로그램은 Cursor 모델에 대해 text 및 image 입력을 광고하는데, 이는 Cursor의 SDK가 이미지 메시지를 수용하며 Cursor 모델이 이를 지원할 것으로 예상되기 때문입니다.

호출 가능한 도구와 표시 전용 도구의 차이, MCP 카탈로그 제한, JSONL ID 패턴, 그리고 pi 토글(toggles)이 Cursor ambient MCP와 어떻게 다른지에 대한 간결한 가이드는 pi의 Cursor 도구 표면(tool surfaces)을 참조하세요.

Cursor 실행은 두 개의 별도 도구 표면을 가진 로컬 Cursor SDK 에이전트를 사용합니다:

Cursor-native 표면 (Cursor-native surface): Cursor 로컬 에이전트 도구, Cursor 설정, 플러그인 및 구성된 Cursor MCP 서버. 이들은 Cursor SDK 로컬 에이전트 경로에 의해 소유된 상태로 유지됩니다.

pi 브리지 표면 (pi bridge surface): pi-cursor-sdk는 브리지가 활성화되어 있고 현재 pi 도구 레지스트리에 노출된 도구가 있는 경우, 실행당 로컬 루프백 MCP 브리지(per-run local loopback MCP bridge)를 통해 브리지 가능한 활성 pi 도구들을 노출합니다.

브리지 기능은 각 Cursor 실행에 대해 pi.getActiveTools() 및 pi.getAllTools()로부터 스냅샷(snapshot)되며, pi가 도구를 노출할 때 도구별 프롬프트 가이드라인(prompt guidelines)도 포함됩니다. Cursor는 활성화된 브리지 가능 pi 도구를 pi__sem_reindex와 같이 충돌 방지(collision-safe)가 된 MCP 이름으로 인식합니다.

해당 도구들이 현재 실행(run) 중에 노출될 때만 그렇습니다. Pi 세션 출력(output), 도구 카드(tool cards), 확인(confirmations), 훅(hooks), 렌더러(renderers), 히스토리(history), 그리고 중단 동작(abort behavior)은 sem_reindex와 같은 실제 pi 도구 이름을 사용합니다.

브리지(bridge)는 Cursor의 MCP 호출을 큐에 넣고, 일반적인 pi toolCall을 방출(emit)한 뒤, 일치하는 pi toolResult를 기다립니다. 그리고 해당 실행(run)이 폐기(disposed), 중단(aborted) 또는 취소(cancelled)되지 않는 한, 새로운 Agent를 생성하지 않고 그 결과를 동일한 라이브 Cursor SDK 실행으로 다시 해결(resolve)합니다. 브리지는 pi 도구의 execute() 핸들러를 직접 호출하지 않습니다.

중복되는 내장 pi 도구(read, bash, write, edit, grep, find, ls)는 Cursor 로컬 에이전트(local agents)가 이미 이에 상응하는 네이티브 기능을 가지고 있기 때문에 기본적으로 숨겨집니다. 확장/커스텀 도구 및 pi의 활성 도구 레지스트리(active tool registry)에 존재하는 중복되지 않는 활성 도구들은 보통 그대로 노출됩니다. 또한 브리지는 활성화되었을 때 cursor_ask_question을 pi__cursor_ask_question으로 노출하여, Cursor가 기본값을 조용히 선택하는 대신 pi UI를 통해 사용자에게 질문할 수 있도록 합니다.

fitchmultz/pi-cursor-sdk

요약

핵심 포인트

댓글