🔮 Claudish

Claude Code. Any Model.

license

Claude Code

기존 AI 구독을 Claude Code와 함께 사용하세요. Anthropic Max, Gemini Advanced, ChatGPT Plus/Codex, Kimi, GLM, OllamaCloud 등과 작동하며, OpenRouter를 통한 580개 이상의 모델 및 완전한 개인 정보 보호를 위한 로컬 모델도 지원합니다.

Website · Documentation · Report Bug

Claudish (Claude-ish)는 로컬 Anthropic API와 호환되는 서버를 통해 요청을 프록시하여 모든 AI 모델로 Claude Code를 실행할 수 있게 해주는 CLI 도구입니다.

지원 제공업체:

• 클라우드: OpenRouter (580개 이상의 모델), Google Gemini, OpenAI, MiniMax, Kimi, GLM, Z.AI, Sakana Fugu, OllamaCloud, OpenCode Zen
• 로컬: Ollama, LM Studio, vLLM, MLX
• 엔터프라이즈: Vertex AI (Google Cloud)

기존 AI 구독 사용하기

여러 개의 AI 구독료를 지불하는 것을 멈추세요. Claudish는 Claude Code의 강력한 인터페이스로 이미 가지고 있는 구독을 사용할 수 있게 해줍니다:

claudish --model ollama@qwen3-coder:latest "your task"

자신만의 키 가져오기 (BYOK)

Claudish는 BYOK AI 코딩 어시스턴트입니다:

• ✅ 이미 가지고 있는 API 키 사용 가능
• ✅ 추가 구독료 없음
• ✅ 완전한 비용 통제 — 사용한 만큼만 지불
• ✅ 모든 제공업체와 작동
• ✅ 세션 중간에 모델 전환 가능

기능

• ✅ 다중 공급자 지원(Multi-provider support): OpenRouter, Gemini, Vertex AI, OpenAI, OllamaCloud 및 로컬 모델 지원

• ✅ 새 라우팅 구문(New routing syntax): 명시적 라우팅을 위해 provider@model[:concurrency] 사용 (예: [email protected])

• ✅ 네이티브 자동 감지(Native auto-detection): gpt-4o, gemini-2.0-flash, llama-3.1-70b와 같은 모델은 자체 API로 자동으로 라우팅됨

• ✅ 직접 API 접근(Direct API access): Google, OpenAI, MiniMax, Kimi, GLM, Z.AI, OllamaCloud, Poe를 직접 청구 방식으로 사용

• ✅ Vertex AI Model Garden: Google 및 파트너 모델 (MiniMax, Mistral, DeepSeek, Qwen, OpenAI OSS) 접근 가능

• ✅ 로컬 모델 지원(Local model support): ollama@, lmstudio@ 구문과 동시성 제어 기능을 사용하여 Ollama, LM Studio, vLLM, MLX 지원

• ✅ 크로스 플랫폼(Cross-platform): Node.js와 Bun 모두에서 작동 (v1.3.0+)

• ✅ 범용 호환성(Universal compatibility): 설치가 필요 없음 (npx 또는 bunx 사용)

• ✅ 대화형 설정(Interactive setup): API 키 및 모델이 제공되지 않은 경우 프롬프트 요청 (설정 제로!)

• ✅ 모니터 모드(Monitor mode): 실제 Anthropic API를 프록시하고 모든 트래픽을 기록 (디버깅용)

• ✅ 프로토콜 준수(Protocol compliance): Claude Code 통신 프로토콜과 1:1 호환

• ✅ 헤드리스 모드(Headless mode): 비대화형 실행을 위한 자동 출력 모드

• ✅ 조용한 모드(Quiet mode): 기본적으로 깔끔한 출력 (로그 오염 없음)

• ✅ JSON 출력(JSON output): 도구 통합을 위한 구조화된 데이터

• ✅ 실시간 스트리밍(Real-time streaming): Claude Code 출력을 실시간으로 확인

• ✅ 병렬 실행(Parallel runs): 각 인스턴스가 격리된 프록시를 받음

• ✅ 자율 모드(Autonomous mode): 플래그를 사용하여 모든 프롬프트를 우회

• ✅ 컨텍스트 상속(Context inheritance): 현재 디렉터리에서 동일한 .claude 설정을 사용하여 실행

• ✅ Claude Code 플래그 전달(Claude Code flag passthrough): 모든 Claude Code 플래그 (--agent, --effort, --permission-mode 등)를 어떤 순서로든 전달 가능

• ✅ 분류기 전달(Classifier passthrough): 하이브리드 설정에서, 메인 루프가 다른 공급자에서 실행되는 동안 Claude Code의 자동 모드 권한 분류기를 실제 Claude (Anthropic)에 유지 (--classifier-provider anthropic)

• ✅ Vision proxy - 비전 모델이 아닌(Non-vision models) 모델도 Claude를 통해 이미지 설명을 자동으로 받아 모든 모델이 '볼' 수 있게 합니다.

설치 (Installation)

빠른 설치 (Quick Install)

# 셸 스크립트 (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/MadAppGang/claudish/main/install.sh | bash

...

필수 조건 (Prerequisites)

• Claude Code - Claude CLI가 설치되어 있어야 합니다.
• 최소 하나의 API 키:
  • OpenRouter API Key - 100개 이상의 모델 접근 가능 (무료 티어 제공)
  • Google Gemini API Key - 직접적인 Gemini 접근용
  • OpenAI API Key - 직접적인 OpenAI 접근용
  • OllamaCloud API Key - 클라우드 호스팅 Ollama 모델 (oc/ 접두사)용
  • 또는 로컬 모델 (Ollama, LM Studio) - API 키 불필요

기타 설치 옵션 (Other Install Options)

설치 없이 사용하기:

npx claudish@latest --model x-ai/grok-code-fast-1 "your prompt"
bunx claudish@latest --model x-ai/grok-code-fast-1 "your prompt"

소스에서 설치하기:

git clone https://github.com/MadAppGang/claudish.git
cd claudish
bun install && bun run build && bun link

빠른 시작 (Quick Start)

0단계: Claudish 스킬 초기화 (최초 1회만)

# 프로젝트 디렉토리로 이동
cd /path/to/your/project

...

이것이 하는 일:

• ✅ .claude/skills/claudish-usage/에 Claudish 사용 스킬을 설치합니다.
• ✅ 자동 서브 에이전트 위임(automatic sub-agent delegation) 기능을 활성화합니다.
• ✅ 파일 기반 지침 패턴(file-based instruction patterns)을 강제합니다.
• ✅ 컨텍스트 창 오염(context window pollution)을 방지합니다.

--init 실행 후, Claude는 자동으로 다음을 수행합니다:

• 외부 모델(Grok, GPT-5 등)을 언급할 때 서브 에이전트를 사용합니다.
• Claudish 사용의 모범 사례를 따릅니다.
• 다양한 작업에 대한 전문 에이전트를 제안합니다.

옵션 1: 이미 비용을 지불하는 구독으로 로그인하기 (API 키 불필요)

ChatGPT Plus/Pro, Antigravity 플랜, Kimi 또는 GLM 코딩 플랜, SuperGrok 구독 또는 Anthropic Max를 사용하고 있다면, claudish login이 이를 직접 사용합니다. API 키나 토큰당 청구 비용이 없습니다.

claudish login                 # 로그인 가능한 모든 제공업체를 상호작용적으로 선택
claudish login codex           # ChatGPT Plus/Pro (OpenAI 자체 PKCE 플로우)
claudish login antigravity     # Antigravity 플랜을 통한 Gemini
...

이후 claudish --probe [email protected]를 실행하여 자격 증명이 올바르게 해결되었는지 확인하고 어떤 제공업체가 실제로 요청을 처리할지 확인할 수 있습니다.

옵션 2: 상호작용 모드 (Interactive Mode)

# 그냥 실행만 하면 됩니다 - API 키와 모델에 대한 프롬프트가 표시됩니다
claudish
...

옵션 3: 환경 변수 사용 시 (With Environment Variables)

# 환경 설정
export OPENROUTER_API_KEY=sk-or-v1-...     # OpenRouter 모델용
export GEMINI_API_KEY=...                   # 직접 Google API용
...

참고: 상호작용 모드에서 OPENROUTER_API_KEY가 설정되어 있지 않다면, 입력하라는 프롬프트가 표시됩니다. 이로 인해 첫 사용이 매우 간단해집니다!

AI 에이전트 사용 (AI Agent Usage)

Claude Code 내에서 실행되는 AI 에이전트의 경우: 파일 기반 패턴 및 서브 에이전트 위임에 대한 포괄적인 지침은 전용 AI 에이전트 가이드를 사용하십시오.

# 전체 AI 에이전트 사용 가이드 출력
claudish --help-ai
...

AI 에이전트를 위한 빠른 참고 자료:

AI 에이전트의 주요 워크플로우 (Main Workflow for AI Agents)

1. 사용 가능한 모델 가져오기:
   복사

   # 모든 모델 목록 보기 또는 검색
   claudish --models
   claudish --models gemini
   

   1

   2

   3

   4

...

2. **서브 에이전트를 통해 Claudish 실행** (권장 패턴):
```typescript
// 메인 대화에서 Claudish를 직접 실행하지 마세요
// Task 도구를 사용하여 서브 에이전트로 위임합니다
const result = await Task({...

3. 파일 기반 지침 패턴 (컨텍스트 오염 방지):
   복사

   // 파일에 지침 작성
   const instructionFile = `/tmp/claudish-task-${Date.now()}.md`;
   const resultFile = `/tmp/claudish-result-${Date.now()}.md`;
   

   1

   2

   3

   4

...

**핵심 원칙:**
- ✅ 컨텍스트 창 오염(context window pollution)을 방지하기 위해 파일 기반 패턴 사용
- ✅ 직접 실행하는 대신 서브 에이전트(sub-agents)에게 위임
- ✅ 요약본만 반환 (전체 대화 기록 아님)
- ✅ 작업에 적합한 모델 선택 (사용법은 `--models` 또는 `--models-top` 참조)

**리소스:**
- 전체 AI 에이전트 가이드: `claudish --help-ai`
- 스킬 문서: `skills/claudish-usage/SKILL.md` (리포지토리 루트에 위치)
- 모델 통합: `skills/claudish-integration/SKILL.md` (리포지토리 루트에 위치)

## 사용법

### 기본 구문

```bash
claudish [OPTIONS] <claude-args...>

옵션

모든 세부 정보가 포함된 포괄적 참조는 설정 참조(Settings Reference)를 참조하십시오.

플래그 통과(Flag passthrough): 인식되지 않은 모든 플래그는 자동으로 Claude Code로 전달됩니다 (예: --agent, --effort, --permission-mode).

환경 변수

Claudish는 시작 시 현재 디렉토리의 .env 파일을 자동으로 로드합니다. 전체 목록은 설정 참조(Settings Reference)를 참조하십시오.

API 키 (클라우드 모델의 경우 최소 1개 필수)

번들형 엔드포인트 카탈로그 (Bundled Endpoint Catalog)

패키지 내에는 25개의 추가 공급업체(vendor)가 미리 정의된 엔드포인트로 포함되어 있습니다. 각 항목은 로컬에 키가 이미 존재하는 경우에만 표시됩니다 (환경 변수, 별칭 또는 config.apiKeys). 즉, 해당 변수를 설정하면 구성 파일 없이도 vendor@model을 사용하여 작동합니다. 1Password에만 존재하는 키는 행(row)을 활성화하지 않습니다 (활성화는 동기적입니다). 이 경우 predefinedEndpoints.enable을 사용하십시오. 사전 정의된 엔드포인트(Predefined Endpoints)를 참조하십시오.

모든 25개 행은 probe-검증을 거칩니다. 구성된 경로는 공급업체 자체 인증 계층에 도달하는 것이 확인되었으며, 다르게 응답하기 위한 가짜 형제 경로도 포함됩니다. 실시간 검증(live-verified)된 것은 없습니다: 이는 라우팅에 대한 강력한 증거이며 성공적인 턴에서 공급업체의 스트리밍 방언에 대한 약한 증거입니다. 엔드포인트 계층 자체는 실제 API와 종단 간(end to end)으로 검증되었습니다.

Claudish 설정 (Claudish Settings)

Claude Code 호환성 (Claude Code Compatibility)

사용자 지정 엔드포인트 (Custom Endpoints)

우선순위 순서: CLI 플래그 > CLAUDISH_* 환경 변수 > ANTHROPIC_* 환경 변수 > 프로필 설정 > 대화형 선택기.

중요 참고 사항:

• Claude Code 로그인 대화 상자를 억제하려면 ANTHROPIC_API_KEY=sk-ant-api03-placeholder (또는 아무 값)을 설정하세요.
• 대화형 모드에서 API 키가 설정되어 있지 않으면, 입력하라는 메시지가 표시됩니다.

구성 파일 (Configuration Files)

Claudish는 두 가지 범위의 구성 시스템을 사용합니다:

{
  "version": "1.0.0",
  "defaultProfile": "default",
...

**사용자 정의 라우팅 규칙 (Custom routing rules)**은 모델 이름 패턴을 순서가 지정된 제공업체 폴백 체인(provider fallback chains)에 매핑합니다. 패턴은 정확한 이름, 글로브(kimi-*), 그리고 * 와일드카드를 지원합니다. 로컬 .claudish.json 라우팅 규칙은 전역 규칙을 완전히 대체합니다.

프로필 관리는 다음 명령어를 사용합니다:

claudish init [--local|--global]            # 설정 마법사 실행
claudish profile list [--local|--global]    # 프로필 목록 보기
claudish profile add [--local|--global]     # 프로필 추가
...

전체 구성 참조는 Settings Reference를 참고하세요.

1Password 통합