Metadata-Version: 2.4
Name: claude-cli-sdk
Version: 0.1.0
Summary: Python SDK wrapping Claude CLI - Use Skills, Hooks, Slash Commands, Agents without official SDK
Project-URL: Homepage, https://github.com/your-username/claude-cli-sdk
Project-URL: Documentation, https://github.com/your-username/claude-cli-sdk#readme
Project-URL: Repository, https://github.com/your-username/claude-cli-sdk
Project-URL: Issues, https://github.com/your-username/claude-cli-sdk/issues
Author: Claude CLI SDK Contributors
License: MIT
Keywords: agent,ai,anthropic,claude,cli,llm,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# 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 플래그

```bash
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 사용법

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

### 기본 사용
```python
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 호출
```python
# 특정 Skill 호출
result = await sdk.run_with_skill(
    "frontend-design:frontend-design",
    "Create a login form"
)
```

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

### Slash Command 호출
```python
# 슬래시 커맨드 실행
result = await sdk.run_slash_command(
    "code-review:code-review"
)
```

### 동기 API
```python
from claude_sdk import ClaudeSDKSync, ClaudeConfig

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

## SDK 구조

```python
# 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]
```

## 응답 구조

```python
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 플래그로 노출됨**
