code-prompt-client

코딩 에이전트(Claude Code, Codex 등)에게 "말을 거는" 행위를 모듈화한 ESM 클라이언트. 스트리밍 텍스트, 사고(thinking), 도구 호출(tool_use), 종료/에러 이벤트를 통일된 AsyncIterable<ChatEvent> 형태로 노출한다.

현재 어댑터: Claude Code (@anthropic-ai/claude-agent-sdk 기반). Codex 등 다른 어댑터는 추후 추가될 예정이다.

설치

npm i code-prompt-client
# or
pnpm add code-prompt-client

런타임 의존성으로 @anthropic-ai/claude-agent-sdk, @anthropic-ai/sdk를 함께 가져온다. Node.js 18 이상에서 동작한다.

빠른 사용 예시

import { ClaudeCodeClient } from 'code-prompt-client';

const client = new ClaudeCodeClient({
  model: 'claude-opus-4-7',
  allowedTools: ['Read', 'Grep', 'Glob'],
  cwd: process.cwd(),
});

for await (const ev of client.chat('src 폴더 구조를 요약해줘')) {
  switch (ev.type) {
    case 'text':     process.stdout.write(ev.text); break;
    case 'tool_use': console.log(`\n[tool] ${ev.name}`, ev.input); break;
    case 'done':     console.log('\n[done]'); break;
    case 'error':    console.error('\n[error]', ev.error); break;
  }
}

await client.close();

이미지 URL 첨부

for await (const ev of client.chat([
  { type: 'text',  text: '이 다이어그램의 문제점을 짚어줘' },
  { type: 'image', url: 'https://example.com/architecture.png' },
])) {
  if (ev.type === 'text') process.stdout.write(ev.text);
}

진행 도중 취소

const stream = client.chat('레포 전체 보안 감사해줘');
const timer = setTimeout(() => client.cancel(), 10_000);

try {
  for await (const ev of stream) {
    if (ev.type === 'text') process.stdout.write(ev.text);
  }
} finally {
  clearTimeout(timer);
}

AbortController와 엮을 때:

const ac = new AbortController();
ac.signal.addEventListener('abort', () => client.cancel());

for await (const ev of client.chat('테스트 실행하고 실패 원인 찾아줘')) {
  if (ac.signal.aborted) break;
  if (ev.type === 'text') appendToChatUI(ev.text);
}

API

• ClaudeCodeClient — Claude Code 어댑터 구현체.
  • chat(content): AsyncIterable<ChatEvent> — for await로 소비. 진행 중 cancel() 호출 가능.
  • cancel(): Promise<void> — 진행 중인 chat 중단.
  • close(): Promise<void> — 세션 완전 종료. 프로세스 종료 전 한 번만 호출.
  • currentSessionId: string | undefined — resume으로 받은 세션 ID. fresh 세션이면 undefined (SDK가 발급한 진짜 id는 SDK 응답으로 확인).
• MODEL — 지원 모델 식별자 리스트(readonly tuple).
• CodePromptClient — 공통 타입 네임스페이스(UserContent, ChatEvent, Impl 등).

라이선스

MIT © bino