Skip to content

Latest commit

 

History

History

claude-cli

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 

README.md

claude-cli

claude CLI 를 실행하는 TypeScript 라이브러리입니다. npm 에 배포하지 않고 이 저장소의 패키지에서 workspace:* 로 씁니다.

준비

claude CLI 를 설치하고 한 번 실행해 로그인합니다.

사용

import { buildClaudeCommand, ClaudeCli } from "claude-cli";

const command = buildClaudeCommand({
    executionMode: "print",
    prompt: "이 폴더의 테스트 구조를 요약해 주세요",
    tools: ["Read", "Grep", "Glob"],
    permissionMode: "dontAsk",
    maxBudgetUsd: 1,
});

const { result, sessionId } = await new ClaudeCli("claude", 300_000).run(
    command,
    "/path/to/project",
);

API

이름 설명
buildClaudeCommand(request) 요청을 CLI 인자와 stdin 으로 바꿉니다
buildWakeCommand(id, prompt) 멈춘 백그라운드 세션을 같은 ID 로 깨우는 명령을 만듭니다
ClaudeCli.run -p 로 실행하고 결과를 돌려줍니다
ClaudeCli.runCollectingToolCalls 실제 호출된 도구와 결과를 돌려줍니다. stream-json 필요
ClaudeCli.startBackground --bg 로 세션을 띄우고 바로 돌아옵니다
ClaudeCli.stopBackground 백그라운드 세션의 프로세스만 멈춥니다
listClaudeSessions(options) 세션 목록을 읽습니다. 살아 있는 세션에만 pid 가 있습니다

동작

  • 격리: 기본으로 MCP 서버와 사용자 설정을 읽지 않습니다. shouldInheritUserConfig 를 켜면 읽습니다.
  • 프롬프트: 인자가 아니라 stdin 으로 넘겨서 옵션으로 해석되지 않습니다.
  • 비용 상한: maxBudgetUsd 가 0 이면 상한 없이 실행합니다. -p 에서만 적용됩니다.
  • 도구: tools 의 * 는 전체 내장 도구입니다.
  • 세션 ID: sessionId 를 넣으면 새 세션을 그 UUID 로 시작합니다. -p 에서만 쓸 수 있고 resumeSessionId 와 같이 쓸 수 없습니다.
  • 같은 세션 순서: ClaudeCli.run 은 --session-id 나 --resume 이 같은 세션을 가리키는 실행을 한 프로세스 안에서 하나씩 순서대로 실행합니다. 동시에 이어 가면 뒤 실행이 앞 실행의 결과를 보지 못하기 때문입니다. 다른 프로세스에서 실행한 것까지는 막지 않습니다.
  • 추가 인자: additionalArguments 는 맨 뒤에 붙어서 앞의 옵션보다 우선합니다.

오류

모두 ClaudeError 를 상속합니다. CLI 가 시간 초과로 받은 SIGTERM 을 직접 처리해 코드 143 으로 끝나도 ClaudeTimedOutError 입니다.

클래스 상황
InvalidClaudeRequestError 요청 값이 잘못됨
ClaudeFailedError CLI 실행 실패
ClaudeTimedOutError 시간 초과
ClaudeCancelledError 취소됨