claude-cli-sdk 0.1.0

Python SDK wrapping Claude CLI - Use Skills, Hooks, Slash Commands, Agents without official SDK

Python Claude CLI SDK

Claude CLI를 subprocess로 감싸서 Python SDK처럼 사용하는 구현체

핵심 발견: SDK 없이 CLI만으로 모든 기능 사용 가능

공식 SDK가 하는 일 = CLI 호출 + JSON 파싱

┌─────────────────────────────────────────┐
│         Your Python Application          │
├─────────────────────────────────────────┤
│        claude_sdk.py (이 구현체)         │
│  - subprocess.Popen("claude", ...)      │
│  - JSON stream 파싱                      │
│  - 이벤트 핸들링                         │
├─────────────────────────────────────────┤
│              Claude CLI                  │
│  (모든 기능이 플래그로 노출됨)            │
└─────────────────────────────────────────┘

테스트 결과: 모든 기능 동작 확인

기능	CLI 플래그	테스트 결과
Skills 호출	--setting-sources "user,project" + --allowed-tools "Skill"	✅ 성공
Hooks 로드	--setting-sources "user,project"	✅ 성공
Agent (Task tool)	--allowed-tools "Task"	✅ 성공
Slash Command	--allowed-tools "SlashCommand"	✅ 성공
양방향 통신	--input-format stream-json	✅ 성공
MCP 서버	--mcp-config config.json	✅ 지원
CLAUDE.md	--setting-sources "user,project"	✅ 성공

핵심 CLI 플래그

claude -p "prompt" \
  --setting-sources "user,project" \     # Skills, Hooks, CLAUDE.md, Subagents 로드
  --allowed-tools "Skill,Task,SlashCommand,Read,Write,Bash" \
  --output-format stream-json \          # JSON 스트림 출력
  --verbose \                            # stream-json에 필수
  --input-format stream-json \           # 양방향 통신
  --permission-mode acceptEdits \        # 권한 자동 승인
  --mcp-config config.json               # MCP 서버 설정

플래그 상세 설명

플래그	설명
--setting-sources "user,project"	~/.claude/settings.json과 .claude/settings.json에서 Skills, Hooks, CLAUDE.md 로드
--allowed-tools	사용 허용할 도구 목록 (쉼표 구분)
--output-format stream-json	각 이벤트를 JSON 라인으로 출력
--verbose	stream-json 출력에 필수
--permission-mode acceptEdits	파일 편집 자동 승인
--max-turns N	최대 턴 수 제한

실제 테스트 결과

1. Skill 호출 테스트

Tool used: Skill
Skill input: {'skill': 'frontend-design:frontend-design'}
>>> SUCCESS

2. Slash Command 호출 테스트

Tool used: SlashCommand
Command: {'command': '/ralph-wiggum:help'}
>>> SUCCESS

3. Agent (Task tool) 호출 테스트

Tool used: Task
Agent type: Explore
Result: Found 4 Python files in the directory
>>> SUCCESS

Python SDK 사용법

설치

# 의존성 없음 - 표준 라이브러리만 사용
cp claude_sdk.py your_project/

기본 사용

import asyncio
from claude_sdk import ClaudeSDK, ClaudeConfig, PermissionMode

async def main():
    sdk = ClaudeSDK(ClaudeConfig(
        setting_sources=["user", "project"],
        permission_mode=PermissionMode.ACCEPT_EDITS
    ))

    result = await sdk.run("Hello!")
    print(result["result"])

asyncio.run(main())

Skills 호출

# 특정 Skill 호출
result = await sdk.run_with_skill(
    "frontend-design:frontend-design",
    "Create a login form"
)

Agent 호출

# Explore 에이전트로 코드베이스 탐색
result = await sdk.run_with_agent(
    "Explore",
    "Find all Python files"
)

Slash Command 호출

# 슬래시 커맨드 실행
result = await sdk.run_slash_command(
    "code-review:code-review"
)

동기 API

from claude_sdk import ClaudeSDKSync, ClaudeConfig

sdk = ClaudeSDKSync(ClaudeConfig())
result = sdk.run("Hello!")

SDK 구조

# ClaudeConfig - 설정 클래스
@dataclass
class ClaudeConfig:
    model: Optional[str] = None
    permission_mode: PermissionMode = PermissionMode.ACCEPT_EDITS
    output_format: OutputFormat = OutputFormat.STREAM_JSON
    setting_sources: list[str] = ["user", "project"]
    allowed_tools: Optional[list[str]] = None
    mcp_config: Optional[str] = None
    max_turns: Optional[int] = None
    system_prompt: Optional[str] = None

# ClaudeSDK - 메인 클래스
class ClaudeSDK:
    async def run(prompt: str) -> dict
    async def run_with_skill(skill_name: str, prompt: str) -> dict
    async def run_with_agent(agent_type: str, task: str) -> dict
    async def run_slash_command(command: str, args: str) -> dict

    # 양방향 통신
    async def start_session() -> None
    async def send_message(message: str) -> None
    async def read_stream() -> AsyncIterator[StreamEvent]

응답 구조

result = await sdk.run("Hello")

# result 구조
{
    "events": [
        {"type": "system", "session_id": "..."},
        {"type": "assistant", "message": {...}},
        {"type": "result", "result": "..."}
    ],
    "result": {"type": "result", "result": "Hello!"},
    "session_id": "abc123",
    "stderr": None
}

이벤트 타입

타입	설명
system	세션 정보 (session_id 포함)
assistant	Claude 응답 (텍스트, 도구 사용)
tool_use	도구 호출
tool_result	도구 실행 결과
result	최종 결과

파일 구조

claude-cli-sdk-test/
├── claude_sdk.py      # SDK 메인 구현
├── test_sdk.py        # 기본 테스트
├── simple_test.py     # CLI 플래그 테스트
├── real_test.py       # 실제 기능 호출 테스트
└── readme.md          # 이 문서

결론

공식 SDK 없이 Python subprocess로 Claude CLI를 직접 호출하면:

1. Skills - --setting-sources로 로드, --allowed-tools "Skill"로 호출 ✅
2. Hooks - --setting-sources로 자동 적용 ✅
3. Slash Commands - --allowed-tools "SlashCommand"로 호출 ✅
4. Agents - --allowed-tools "Task"로 호출 ✅
5. MCP 서버 - --mcp-config로 설정 ✅
6. CLAUDE.md - --setting-sources로 자동 로드 ✅

SDK = CLI의 편의 래퍼일 뿐, 핵심 기능은 전부 CLI 플래그로 노출됨