진입점 & SDK

Claude Code는 다양한 진입점을 통해 접근할 수 있습니다. CLI(터미널), 데스크톱 앱(Mac/Windows), 웹(claude.ai/code), IDE 확장(VS Code, JetBrains) — 각 진입점은 동일한 코어 엔진을 공유하지만 UI와 전송 계층이 다릅니다. 또한 SDK와 Agent SDK를 통해 프로그래밍 방식으로 Claude Code를 통합할 수 있습니다.

진입점 아키텍처의 핵심 원칙:

• 공유 코어: QueryEngine, 도구 시스템, 권한 시스템, MCP 통합은 모든 진입점에서 동일
• 분리된 표면: UI 렌더링, 전송 프로토콜, 인증 방식은 진입점마다 독립
• 유연한 통합: SDK를 통해 CI/CD, 자동화, 커스텀 에이전트 구축 가능

entrypoints/cli.tsx가 메인 CLI 진입점입니다. 터미널에서 claude 명령을 실행하면 이 파일이 가장 먼저 로드됩니다.

패스트 패스 분기

CLI 진입점은 무거운 모듈 로드 전에 빠르게 처리할 수 있는 경로를 먼저 체크합니다:

• --version / -v — 버전 문자열 출력 후 즉시 종료
• --daemon-worker — 데몬 워커 프로세스 실행
• remote-control / bridge — 브릿지 모드 실행

// cli.tsx — 패스트 패스: main.tsx를 전혀 임포트하지 않음
const args = process.argv.slice(2)
if (args.length === 1 && (args[0] === '--version' || args[0] === '-v')) {
  console.log(`${MACRO.VERSION} (Claude Code)`)
  return
}

Commander.js 인수 파싱

패스트 패스를 통과하면 Commander.js가 인수를 파싱합니다. 주요 CLI 플래그:

• --model — 사용할 모델 지정 (예: claude-sonnet-4-6)
• --print / -p — 비대화형 모드, 결과 출력 후 종료
• --resume — 이전 세션 재개
• --session — 특정 세션 ID로 시작
• --worktree — git worktree 생성 후 실행
• --bare — SDK/스크립트용 최소 시작 모드
• --mcp-config — MCP 서버 구성 파일 경로

Claude Code는 프로그래밍 방식으로 사용할 수 있습니다. @anthropic-ai/claude-code 패키지가 공식 SDK를 제공합니다.

query() 함수

query()는 SDK의 핵심 진입점으로, 메시지를 전송하고 SDKMessage 스트림을 반환합니다. AsyncGenerator 패턴을 사용하여 실시간으로 응답을 스트리밍합니다.

import { query, SDKMessage } from '@anthropic-ai/claude-code';

const messages: SDKMessage[] = [];
for await (const msg of query({
  prompt: "Fix the TypeScript errors in src/",
  options: {
    model: 'claude-sonnet-4-6',
    maxTurns: 10,
    permissionMode: 'acceptEdits',
  }
})) {
  messages.push(msg);
  if (msg.type === 'assistant') {
    console.log(msg.message.content);
  }
}

SDK 옵션

query()에 전달할 수 있는 주요 옵션:

• model — 사용할 모델 (기본: 설정된 모델)
• systemPrompt — 커스텀 시스템 프롬프트
• tools — 활성화할 도구 목록
• maxTurns — 최대 턴 수 제한
• permissionMode — 권한 모드 ('default', 'acceptEdits', 'bypassPermissions')
• cwd — 작업 디렉토리

SDKMessage 타입

스트림에서 반환되는 메시지 타입:

• assistant — 어시스턴트 응답 (텍스트, 도구 호출)
• user — 사용자 메시지 (도구 결과 포함)
• system — 시스템 이벤트
• result — 최종 결과 메타데이터

@anthropic-ai/claude-agent-sdk 패키지는 커스텀 에이전트를 구축하기 위한 고급 SDK입니다. Claude Code의 핵심 기능을 재사용하면서 자체 로직을 추가할 수 있습니다.

AgentRuntime 클래스

AgentRuntime은 에이전트의 실행 환경을 관리합니다:

• 도구 정의와 등록 — 커스텀 도구를 정의하고 에이전트에 등록
• 세션 관리 — 대화 컨텍스트와 상태 추적
• 이벤트 루프 — 모델 호출 → 도구 실행 → 결과 반환 사이클

import { AgentRuntime } from '@anthropic-ai/claude-agent-sdk';

const runtime = new AgentRuntime({
  model: 'claude-sonnet-4-6',
  tools: [myCustomTool, fileReadTool],
  systemPrompt: 'You are a code review assistant.',
});

const result = await runtime.run({
  prompt: 'Review the latest PR changes',
});

커스텀 도구 정의

Agent SDK에서 도구는 이름, 설명, 입력 스키마, 실행 함수로 구성됩니다. Claude Code의 기본 도구(파일 읽기/쓰기, Bash 등)를 재사용하거나 완전히 새로운 도구를 정의할 수 있습니다.

VS Code 확장과 JetBrains 플러그인은 IDE 내에서 Claude Code를 사용할 수 있게 합니다.

전송 프로토콜

IDE 확장은 CLI의 stdio 대신 전용 전송 프로토콜을 사용합니다:

• sse-ide — Server-Sent Events 기반 IDE 전송
• ws-ide — WebSocket 기반 IDE 전송

전송 프로토콜은 다르지만 내부적으로 동일한 QueryEngine과 도구 시스템을 사용합니다.

IDE 컨텍스트 공유

IDE 확장의 핵심 장점은 풍부한 컨텍스트 공유입니다:

• 열린 파일: 현재 에디터에서 열린 파일 목록과 내용
• 선택 영역: 사용자가 선택한 코드 범위
• 진단: 린트 오류, 타입 오류, 경고 등 IDE 진단 정보
• 대화형 diff 미리보기: 코드 변경 사항을 IDE의 diff 뷰어로 미리보기

claude.ai/code는 브라우저 기반 Claude Code 인터페이스를 제공합니다.

브라우저 기반 인터페이스

로컬 설치 없이 웹 브라우저에서 Claude Code를 사용할 수 있습니다. 터미널 에뮬레이션을 포함하여 CLI와 유사한 경험을 제공합니다.

CCR (Claude Code in Repositories) 통합

CCR은 클라우드 원격 환경에서 Claude Code 세션을 실행합니다:

• 원격 세션 생성 및 관리 — GitHub 레포지토리를 클라우드 환경에 클론하여 작업
• 격리된 실행 환경 — 각 세션이 독립적인 컨테이너에서 실행
• 자동 환경 설정 — 의존성 설치, 빌드 도구 구성 자동화

Mac과 Windows용 네이티브 데스크톱 앱은 CLI의 모든 기능을 GUI 환경에서 제공합니다.

주요 특징

• 터미널 에뮬레이터 내장: 별도의 터미널 앱 없이 Claude Code를 바로 실행
• 시스템 트레이 통합: 백그라운드 실행, 빠른 접근, 알림
• 자동 업데이트: 새 버전이 릴리스되면 자동으로 업데이트
• 네이티브 경험: OS별 키보드 단축키, 드래그 앤 드롭, 파일 시스템 통합

데스크톱 앱은 내부적으로 CLI와 동일한 코어 엔진을 실행합니다. UI 레이어만 Ink(터미널) 대신 네이티브 윈도우로 대체됩니다.

모든 진입점은 공통 코어 위에 구축됩니다. 공유 컴포넌트와 진입점별 차이를 명확히 이해하는 것이 중요합니다.

모든 진입점이 공유하는 것

• QueryEngine: 모델 호출, 턴 관리, 컨텍스트 구성의 핵심 엔진
• 도구 시스템: 파일 읽기/쓰기, Bash, Glob, Grep 등 동일한 도구 세트
• 권한 시스템: 도구 실행 전 사용자 승인, 정책 기반 자동 승인
• MCP 통합: Model Context Protocol을 통한 외부 도구 확장
• 컨텍스트 관리: CLAUDE.md 로딩, 컨텍스트 압축, 프롬프트 캐시

진입점별로 다른 것

• UI 렌더링: CLI는 Ink(React 기반 TUI), IDE는 WebView, 웹은 브라우저 DOM, 데스크톱은 네이티브 윈도우
• 전송 계층: CLI는 stdio, IDE는 SSE/WebSocket, 웹은 HTTP, SDK는 프로세스 내 호출
• 인증 방식: CLI는 OAuth/API 키, IDE는 토큰 전달, 웹은 세션 쿠키, CCR은 서비스 인증

--bare 플래그(또는 CLAUDE_CODE_SIMPLE 환경 변수)는 SDK와 스크립트 사용에 최적화된 최소 시작 모드를 활성화합니다.

건너뛰는 단계

Bare 모드에서는 다음 시작 단계가 모두 건너뛰어집니다:

• UDS 메시징: Unix Domain Socket 서버 시작 안 함
• 팀메이트 스냅샷: 스웜/팀메이트 정보 수집 안 함
• 세션 메모리: 이전 세션 컨텍스트 로드 안 함
• 플러그인 훅: 플러그인 사전 로드 안 함
• 지연 프리페치: startDeferredPrefetches() 실행 안 함

유지되는 단계

Bare 모드에서도 다음은 여전히 실행됩니다:

• 인증 확인
• 마이그레이션
• Commander 인수 파싱
• 분석 비컨 (tengu_started)