cli-switch
코딩 CLI를 위한 AI 에이전트 기능 라우터.
npm version
Node.js
License: MIT
TypeScript
cli-switch는 AI 코딩 에이전트를 위한 명령줄 오케스트레이션 레이어(orchestration layer)입니다. 이 도구는 작업을 적절한 에이전트로 라우팅하고, 게이트웨이 자격 증명(gateway credentials)을 주입하며, 모델 등급(model tiers)을 선택하고, 자식 프로세스 환경을 격리하며, 스크립트 및 상위 레벨 에이전트가 소비할 수 있는 텍스트 또는 JSON 출력을 반환합니다.
현재 릴리스: [email protected]
언어 지원 (Languages)
영어 (English)
개요 (What It Is)
현대의 코딩 에이전트는 강력하지만, 모든 CLI는 서로 다른 인증(authentication), 모델 플래그(model flags), 환경 변수(environment variables), 강점 및 실패 모드(failure modes)를 가지고 있습니다. cli-switch는 이러한 도구들 위에 라우팅 레이어를 추가합니다:
task
-> 의도 및 기능 감지 (intent and capability detection)
-> 에이전트 및 등급 선택 (agent and tier selection)
...
이는 여러 코딩 에이전트를 위해 안정적인 인터페이스가 필요한 개발자, 자동화 스크립트, 그리고 에이전트 프레임워크를 위해 설계되었습니다.
사용 사례 (What You Can Use It For)
- Claude Code와 Codex CLI 간에 코딩 작업을 라우팅합니다.
- 지원되는 에이전트 전반에 걸쳐 하나의 게이트웨이 또는 자체 호스팅 릴레이 API 키를 사용합니다.
- 각 에이전트의 글로벌 설정을 변경하지 않고 OpenRouter 스타일의 키를 재사용할 수 있습니다.
- 모델 토큰을 소모하기 전에 건식 실행(dry-run) 라우팅 결정을 수행할 수 있습니다.
- 안정적인 JSON 출력이 필요한 상위 레벨 에이전트 워크플로우를 구축합니다.
- 검토, 테스트 작성, 리팩터링, 설명, 분석 및 수정 작업을 전송합니다 (Dispatch).
- 부모 세션 변수가 자식 에이전트 프로세스에 노출되는 것을 방지합니다.
- 진단(diagnostics) 및 인증 확인을 통해 로컬 에이전트의 준비 상태를 검사합니다.
- 프롬프트 템플릿을 사용하여 재사용 가능한 기술 워크플로우를 정의합니다.
- 실제 프로젝트에 영향을 주지 않고 격리된 작업 트리(worktrees) 또는 임시 복사본에서 에이전트를 실행합니다.
적합한 상황 (Good Fit)
| 시나리오 | cli-switch가 도움이 되는 이유 |
|---|
| 다중 에이전트 코딩 워크플로우 | 하나의 도구를 하드코딩하는 대신 작업별로 Claude Code 또는 Codex를 선택합니다. |
| ... | |
현재 상태 (Current Status)
[email protected] — 로드맵의 모든 5개 단계가 완료되었습니다. 테스트 파일 51개, 테스트 케이스 640개가 통과했습니다.
구현된 기능:
- 스마트 라우팅을 사용한
cli-switch run <task> 실행 기능.
--agent claude-code|codex를 이용한 에이전트 재정의(Agent override) 기능.
- 다양한 실행 모드:
single, write_review, write_test_fix, patch-only, temp-copy, worktree.
- 계층별 라우팅:
economy, standard, premium.
- 게이트웨이 별칭(Gateway aliases):
SWITCH_*, SWITCH_RELAY_*, OPENROUTER_*.
- 설정 레이어링(Config layering): 전역 설정 파일
~/.cli-switch/config.yaml + 프로젝트별 .cli-switch.yaml + CLI 플래그 (우선순위: CLI > 프로젝트 > 전역 > 환경 변수).
- 설정 명령어: 점 표기법 키(dot-path keys)를 사용하고, 타입 강제 변환(type coercion),
--project/--global 범위 지정, --json 출력을 지원하는 config show/set/reset.
- 출력 유효성 검사 스키마 및 경계가 설정된 자동 복구(bounded auto-repair)를 통한 diff 유효성 검사 기능.
- 실행 격리:
patch-only 모드, 임시 프로젝트 사본, git worktree 사용.
- 스킬 정의: 로컬
.cli-switch/skills/ 및 ~/.cli-switch/skills/ 경로에서 skill list/show/run 명령어를 통해 관리 가능.
- 자동화를 위한 JSON 출력 기능.
- 진단 도구:
resolve, env, auth status, doctor, list 등의 명령어 제공.
- 프로세스 환경 격리 및 게이트웨이 HOME 격리 지원.
- 전체 TypeScript 빌드와 자동화된 테스트 스위트(automated test suite).
알려진 제한 사항:
--strategy balanced|high_quality|low_cost는 인수로 받아들여지지만, 아직 런타임 비용 전략 선택기(runtime cost strategy selector)로 구현되지는 않았습니다.
- 게이트웨이 주입 기능은 현재 Claude Code와 Codex를 대상으로 합니다.
설치
npm install -g cli-switch
확인:
cli-switch --version
cli-switch doctor --json
소스에서 설치:
git clone https://github.com/zhoutian1995/cli-switch.git
cd cli-switch
npm install
...
빠른 시작
라우팅 결정 미리보기:
cli-switch run "refactor the auth module" --dry-run
자동 라우팅으로 실행하기:
cli-switch run "write tests for the payment parser"
특정 에이전트 강제 지정:
cli-switch run "fix this TypeScript error" --agent codex
cli-switch run "review this architecture change" --agent claude-code
실행 모드 사용하기:
cli-switch run "implement login validation" --execution write_test_fix
cli-switch run "refactor safely" --execution worktree
게이트웨이 및 릴레이 설정 (Gateway And Relay Configuration)
선호되는 변수:
export SWITCH_API_KEY=your-gateway-key
export SWITCH_BASE_URL=https://your-relay.example.com/v1
export SWITCH_MODEL_ECONOMY=your-economy-model
...
셀프 호스팅 릴레이 별칭 (Self-hosted relay aliases):
export SWITCH_RELAY_API_KEY=your-relay-key
export SWITCH_RELAY_BASE_URL=https://your-relay.example.com/v1
OpenRouter 호환 별칭 (OpenRouter-compatible aliases):
export OPENROUTER_API_KEY=sk-or-v1-xxx
export OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
우선순위:
SWITCH_* > SWITCH_RELAY_* > OPENROUTER_*
게이트웨이 모드가 활성화된 경우:
| 에이전트 (Agent) | 주입되는 변수 (Injected variables) | 모델 플래그 (Model flag) |
|---|
| Claude Code | ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL | --model |
| Codex CLI | OPENAI_API_KEY, OPENAI_BASE_URL | -m |
설정 파일 (Config Files)
전역 설정: ~/.cli-switch/config.yaml
cli-switch config set gateway.base_url https://your-relay.example.com/v1
cli-switch config set gateway.api_key your-key
cli-switch config set gateway.models.economy your-economy-model
...
프로젝트 설정: .cli-switch.yaml (저장소별, 전역 설정을 덮어씀)
cli-switch config set --project gateway.default_tier premium
cli-switch config show
설정 우선순위: CLI 플래그 > 프로젝트 설정 > 전역 설정 > 환경 변수.
명령어 (Commands)
cli-switch resolve
cli-switch env
cli-switch auth status
...
현재 run 옵션:
--mode <모드> single|orchestrator|handoff|review
--agent <에이전트> claude-code|codex
--execution <모드> single|write_review|write_test_fix|patch_only|temp_copy|worktree
...
아키텍처 (Architecture)
cmd/ CLI 명령어 진입점(entrypoints)
src/core/router/ 기능 및 모델 라우팅
src/core/gateway/ 게이트웨이 설정 및 환경 변수 주입
...
개발 (Development)
npm run build
npm test
npm run smoke
...
검증 기준선(Verification baseline):
로드맵 — 완료 ✅
계획된 5가지 단계 모두 구현:
- 런타임 계약 폐쇄 (Runtime Contract Closure) — resolver 엄격성, 플랫폼/바이너리 사전 검사(preflight), 오류 코드 목록화.
- 설정 커버리지 (Configuration Coverage) — 전역/프로젝트 설정 계층화,
config show/set/reset 기능 구현.
- 출력 유효성 검사 및 복구 (Output Validation and Repair) — 기능 스키마(capability schemas), 차이점(diff) 유효성 검사, 경계가 있는 자동 복구(bounded auto-repair).
- 실행 격리 (Execution Isolation) — 패치 전용, 임시 프로젝트 사본, git worktree 모드 지원.
- 스킬 워크플로우 기반 구축 (Skill Workflow Foundation) — 로컬 스킬 정의,
skill run 기능 구현.
중국어 원문 번역
이것은 무엇인가요
cli-switch는 AI 프로그래밍 CLI를 위한 **Agent Capability Router (에이전트 능력 라우터)**입니다.
이는 새로운 모델도 아니며, Claude Code나 Codex CLI의 대체재도 아닙니다. 대신, 이들 도구 위에 위치하는 통합 진입점(unified entry layer) 역할을 합니다:
작업 입력
-> 의도 및 능력 식별
-> 에이전트와 모델 단계 선택
...
핵심 목표는 상위 Agent, 자동화 스크립트 또는 개발자가 더 이상 "이 작업을 수행하는 데 어떤 Agent, 어떤 모델, 어떤 API Key, 어떤 명령어 매개변수를 사용해야 하는지"에 직접 신경 쓰지 않도록 하는 것입니다. 사용자(개발자)가 작업만 설명하면, cli-switch가 적절한 실행기(executor)로 작업을 라우팅하는 역할을 담당합니다.
왜 필요한가요
AI 프로그래밍 도구는 점점 늘어나고 있지만, 이들의 호출 방식은 통일되어 있지 않습니다:
- Claude Code, Codex CLI 등 각 도구마다 서로 다른 인증 방식과 환경 변수를 사용합니다.
- Agent마다 강점을 가진 작업이 다릅니다. 예를 들어 복잡한 리팩토링, 테스트 생성, 오류 수정, 코드 설명 등이 있습니다.
- 자체 구축 중계 스테이션(middleware), OpenRouter, 또는 타사 Gateway는 일반적으로 동일한 API Key 세트를 여러 Agent의 네이티브 변수로 매핑해야 합니다.
- 상위 Agent는 각 CLI에서 나오는 비정형화된 터미널 출력을 파싱하는 대신 안정적인 JSON 출력을 필요로 합니다.
- 자식 프로세스가 사용자 전역 HOME 및 세션 변수를 직접 상속받게 되면, 설정 오염(configuration pollution)과 재현 불가능한 동작을 유발하기 쉽습니다.
cli-switch가 해결하는 문제는 바로 "다중 Agent 능력 호출의 표준화"입니다. 즉, 서로 다른 CLI를 통합된 능력으로 포장하여, 시스템이 작업에 따라 적절한 Agent, 모델 단계, 그리고 실행 전략을 자동으로 선택하게 만드는 것입니다.
- Claude Code와 Codex CLI 간에 작업 라우팅을 수행합니다.
--agent를 사용하여 특정 에이전트를 강제 지정할 수 있습니다.
--tier economy|standard|premium를 사용하여 비용/품질 등급을 표현합니다.
--execution single|write_review|write_test_fix|patch_only|temp_copy|worktree를 사용하여 실행 프로세스를 표현합니다.
- 자체 구축한 중계소(relay) 또는 OpenRouter와 호환되는 키를 Claude/Codex가 필요로 하는 네이티브 환경 변수로 주입합니다.
--dry-run을 사용하여 라우팅 결정을 확인하고, 모델 호출의 맹목적인 소모를 방지합니다.
--json을 사용하여 스크립트, CI(Continuous Integration), 상위 에이전트 또는 자동화 시스템에 연결합니다.
- 전역 설정
~/.cli-switch/config.yaml과 프로젝트 설정 .cli-switch.yaml의 다층적 덮어쓰기(multi-layer override)를 지원합니다.
config show/set/reset 명령으로 설정을 관리하며, dot-path, 타입 자동 변환, --project/--global을 지원합니다.
- 출력 검증 및 자동 복구 파이프라인을 제공하며, 능력(capability) 출력 스키마와 diff 검증을 포함합니다.
- Patch-only, 임시 프로젝트 사본, git worktree의 세 가지 격리 실행 모드를 지원합니다.
- 로컬 스킬(Skill) 정의와
skill list/show/run을 통해 재사용 가능한 워크플로우를 제공합니다.
- 자식 프로세스 환경을 격리하고 부모 프로세스의 세션 변수를 정리합니다.
현재 상태
[email protected] — 로드맵 단계 5개 모두 완료. 테스트 파일 51개, 테스트 통과 640개.
현재 한계:
--strategy balanced|high_quality|low_cost는 현재 수락되고 경고(warning)가 표시되지만, 실제 런타임 비용 전략으로 아직 적용되지 않았습니다.
- 게이트웨이 주입은 현재 주로 Claude Code와 Codex를 대상으로 합니다.
설치 및 빠른 시작
npm install -g cli-switch
cli-switch --version
cli-switch doctor --json
라우팅 결정 확인:
cli-switch run "도움이 필요해, auth 모듈을 리팩토링 해줘" --dry-run
에이전트 자동 선택 실행:
cli-switch run "payment parser를 위한 테스트 코드를 작성해 줘"
에이전트 지정:
cli-switch run "이 TypeScript 오류를 수정해 줘" --agent codex
격리 실행:
cli-switch run "이 모듈을 리팩토링 해줘" --execution worktree
설정 파일
전역 설정 ~/.cli-switch/config.yaml:
cli-switch config set gateway.base_url https://your-relay.example.com/v1
cli-switch config set gateway.api_key your-key
cli-switch config set gateway.models.economy your-economy-model
...
프로젝트 설정 .cli-switch.yaml(각 저장소별 독립적, 전역 설정 덮어쓰기):
cli-switch config set --project gateway.default_tier premium
우선순위: CLI 인자 > 프로젝트 설정 > 전역 설정 > 환경 변수.
중계소(Relay) / 게이트웨이 설정
export SWITCH_API_KEY=your-gateway-key
export SWITCH_BASE_URL=https://your-relay.example.com/v1
export SWITCH_MODEL_ECONOMY=your-economy-model
...
우선순위:
SWITCH_* > SWITCH_RELAY_* > OPENROUTER_*
로드맵 — 모두 완료 ✅
- 런타임 계약 폐쇄 (Runtime Contract Closure) — 해석 강화, 플랫폼/바이너리 사전 검사, 오류 코드 순환 구조.
- 구성(설정) 범위 커버리지 (Configuration Coverage) — 전역/프로젝트 설정 계층화,
config show/set/reset.
- 출력 유효성 검사 및 복구 (Output Validation and Repair) — 능력 출력 스키마 (schema), diff 검증, 유한 자동 복구.
- 실행 격리 (Execution Isolation) — patch-only, 임시 프로젝트 사본, git worktree 격리.
- 스킬 워크플로우 기반 (Skill Workflow Foundation) — 로컬 Skill 정의,
skill run.
무엇인가 (What)
cli-switch는 AI 코딩 CLI를 위한 Agent Capability Router입니다.
이는 Claude Code나 Codex CLI를 대체하는 것이 아니라, 그것들 위에 놓이는 통합 실행 레이어입니다.
태스크 입력
-> 의도 및 능력 판별
-> Agent와 모델 Tier 선택
...
개발자, 자동화 스크립트, 상위 Agent 프레임워크가 여러 AI 코딩 Agent를 하나의 안정적인 CLI 인터페이스에서 호출할 수 있도록 하는 것이 목적입니다.
왜 필요한가 (Why)
AI 코딩 CLI는 강력하지만, 실제 운영에서는 다음과 같은 문제점들이 있습니다.
- 툴마다 인증 방식, 환경 변수, 모델 지정 플래그가 다릅니다.
- Agent별로 강점이 다르기 때문에 작업에 따른 사용 구분이 필요합니다.
- 자체 LLM relay나 OpenRouter 호환 Gateway를 사용할 경우, 동일한 Key를 각 CLI의 네이티브 환경 변수로 변환할 필요가 있습니다.
- 상위 Agent나 CI에서는 터미널용 비구조화 출력보다 안정적인 JSON 출력이 필요합니다.
cli-switch는 이러한 문제들을 "Capability Routing"이라는 형태로 표준화합니다.
현재 상태 (Current Status)
[email protected] — 5가지 로드맵 단계 모두 완료. 51개 테스트 파일, 640개 테스트 통과.
구현된 기능:
cli-switch run 스마트 라우팅.
--agent, --tier, --execution 플래그.
- 6가지 실행 모드:
single, write_review, write_test_fix, patch_only, temp_copy, worktree.
- 전역 + 프로젝트 설정 레이어,
config show/set/reset.
- 출력 유효성 검사 + diff 자동 복구.
- 로컬 Skill 정의 +
skill list/show/run.
- 자식 프로세스 환경 격리.
제한 사항:
--strategy는 수용하지만, 실행 시 비용 전략으로는 미구현되었습니다.
- Gateway 주 대상은 Claude Code와 Codex입니다.
로드맵 (Roadmap) — 완료 ✅
- 런타임 계약 폐쇄 (Runtime Contract Closure) — resolver 엄격화, preflight checks, error-code closure.
- 구성(설정) 범위 커버리지 (Configuration Coverage) — 전역/프로젝트 설정,
config show/set/reset.
- 출력 유효성 검사 및 복구 (Output Validation and Repair) — capability schema, diff validation, bounded repair.
- 실행 격리 (Execution Isolation) — patch-only, temp copy, worktree 모드.
- 스킬 워크플로우 기반 (Skill Workflow Foundation) — 로컬 Skill 정의,
skill run.
cli-switch는 AI 코딩 CLI를 위한 Agent Capability Router입니다. 이는 Claude Code나 Codex CLI를 대체하는 도구가 아니라, 여러 코딩 Agent 위에서 하나의 안정적인 실행 인터페이스를 제공하는 오케스트레이션 레이어입니다.
작업 입력
-> 의도와 Capability 감지
-> Agent와 모델 Tier 선택
...
개발자, 자동화 스크립트, 상위 Agent 프레임워크가 여러 AI 코딩 CLI를 일관된 방식으로 호출할 수 있게 만드는 것이 목표입니다.
Current Status / 현재 상태
[email protected] — 5개 로드맵 단계 모두 완료. 51 테스트 파일, 640 테스트 통과.
구현된 기능:
cli-switch run 스마트 라우팅.
--agent, --tier, --execution 플래그.
- 6개 실행 모드:
single, write_review, write_test_fix, patch_only, temp_copy, worktree.
- 글로벌 + 프로젝트 설정 레이어,
config show/set/reset.
- 출력 검증 + diff 자동 복구.
- 로컬 Skill 정의 +
skill list/show/run.
- 자식 프로세스 환경 격리.
제한:
--strategy는 옵션으로 받지만 실제 runtime cost strategy로는 아직 동작하지 않음.
- Gateway 주입은 현재 Claude Code와 Codex가 주요 대상.
Roadmap / 로드맵 — 완료 ✅