ccuse: Claude Code CLI를 위한 프로필 스위처 (Profile Switcher)

이 저장소에는 Claude Code CLI를 위해 설계된 명령줄 프로필 스위처(command-line profile switcher)인 ccuse가 포함되어 있습니다. 이 도구를 통해 개발자는 전역(globally), 프로젝트별(per project), 또는 단일 임시 셸 세션(single temporary shell session)이라는 세 가지 구성 범위(configuration scopes)에 걸쳐 Claude Code의 기본 계정/구독 모드와 호환 가능한 API 제공업체 간을 전환할 수 있습니다.

ccuse가 제공하는 것

저장소 문서에 따르면, ccuse는 여러 AI API 제공업체와 함께 Claude Code를 사용하는 개발자들의 특정 요구 사항을 해결합니다. 매번 다른 모델 제공업체를 사용하고 싶을 때마다 구성 파일(configuration files)을 수동으로 편집하거나 여러 세트의 환경 변수(environment variables)를 관리하는 대신, ccuse는 간단한 셸 명령어를 통해 프로필을 생성, 저장 및 활성화합니다.

문서화된 기능은 다섯 가지 API 제공업체 프로필을 지원합니다:

1. Claude (Native) - Claude Code 계정/구독 또는 Anthropic API를 직접 사용
2. Volcengine Ark - Volcengine Ark Agent Plan을 사용
3. GLM via Ark Agent Plan - Volcengine Ark Agent Plan을 통해 GLM 모델을 사용
4. Kimi - Moonshot AI의 Kimi API를 사용
5. MiniMax - MiniMax API를 사용

각 프로필은 특정 모델에 대응합니다. 예를 들어, Volcengine Ark 프로필은 doubao-seed-2-0-code-preview-260215를 지원하며, GLM 프로필은 GLM-5.1, GLM-4.7, GLM-4.7-FlashX를 지원하고, Kimi 프로필은 kimi-k2.6을 지원하며, MiniMax 프로필은 MiniMax-M2.7 및 MiniMax-M2.7-highspeed를 지원합니다. 이 모델들의 컨텍스트 윈도우(Context windows)는 각 제공업체의 문서화된 사양에 따라 최대 256K에 달합니다.

세 가지 구성 범위

문서에 설명된 핵심 설계 특징 중 하나는 각기 다른 지속성 특성(persistence characteristics)을 가진 세 가지 다른 범위에서 프로필을 적용할 수 있는 능력입니다.

전역 범위 (Global Scope)

전역 프로필 스위칭 (Global profile switching)은 메인 Claude Code settings.json 파일을 수정합니다. 활성화되면, 선택된 프로필이 시스템 어디에서든 실행되는 모든 Claude Code 인스턴스의 기본값 (default)이 됩니다. 이 도구는 프로필을 전환하기 전에 현재 설정 파일의 백업을 자동으로 생성합니다.

이 범위 (scope)에서의 명령어는 다음과 같습니다:

• ccuse claude 또는 ccuse global claude - 네이티브 Claude 프로필로 전환
• ccuse ark 또는 ccuse global ark - Volcengine Ark 프로필로 전환
• ccuse glm 또는 ccuse global glm - GLM 프로필로 전환
• ccuse kimi 또는 ccuse global kimi - Kimi 프로필로 전환
• ccuse minimax 또는 ccuse global minimax - MiniMax 프로필로 전환

프로젝트 범위 (Project Scope)

프로젝트 범위 (Project-scoped) 프로필을 사용하면 특정 리포지토리 (repository) 또는 작업 디렉토리 (working directory)가 전역 기본값과 다른 제공자 (provider)를 사용하도록 설정할 수 있습니다. 이는 모델 요구 사항이 서로 다른 여러 프로젝트를 작업할 때나, 전역 기본 설정에 영향을 주지 않고 특정 제공자의 테스트를 격리하여 수행하고 싶을 때 유용합니다.

프로젝트 범위는 현재 작업 디렉토리에 ./.claude/settings.json 파일을 생성하며, 전역 ~/.claude/settings.json 파일은 건드리지 않습니다. Claude Code는 해당 디렉토리에서 실행될 때 프로젝트 수준의 설정을 자동으로 읽어옵니다.

명령어는 다음과 같습니다:

• ccuse project <profile> - 현재 프로젝트에 프로필 유지
• ccuse project show - 현재 프로젝트 프로필 표시
• ccuse project rm - 프로젝트 전용 프로필 제거

세션 범위 (Session Scope)

세션 수준 (Session-level) 스위칭은 전적으로 환경 변수 (environment variables)를 통해 작동하며, 영구적인 파일 변경을 수행하지 않습니다. 이는 일회성 테스트를 하거나, 영구적인 설정을 변경하지 않고 일시적으로 다른 제공자를 시도해보고 싶을 때 유용합니다.

eval "$(ccuse local <profile>)"를 사용하면, 해당 프로필의 환경 변수가 현재 셸 (shell) 세션에 로드됩니다. ccuse start <profile> 명령어는 환경 변수를 로드한 즉시 Claude Code를 실행합니다.

빠른 시작을 위한 단축키(shortcuts)도 제공됩니다:

• ccuse cc - Claude 프로필 + 실행
• ccuse ca - Ark 프로필 + 실행
• ccuse ck - Kimi 프로필 + 실행
• ccuse cg - GLM 프로필 + 실행
• ccuse cm - MiniMax 프로필 + 실행

-c 또는 --continue 플래그를 추가하여 마지막 Claude Code 대화를 재개할 수 있습니다.

프로필 관리 기능 (Profile Management Features)

프로필 전환 외에도, 이 도구에는 다음과 같은 여러 프로필 관리 명령어가 포함되어 있습니다:

• ccuse init-<provider> - 프로필 템플릿을 생성하거나 재설정합니다.
• ccuse list - 사용 가능한 모든 프로필을 나열하고 활성화된 프로필을 표시합니다.
• ccuse show - 비밀 정보(secrets)를 마스킹 처리하여 현재 Claude Code 설정을 보여줍니다.
• ccuse doctor - 설정을 확인하고, 활성화된 스코프(scopes)를 점검하며, 다음 단계를 제안합니다.
• ccuse edit <name> - 편집을 위해 프로필 파일을 엽니다.
• ccuse remove <name> - 확인 절차를 거친 후 프로필을 삭제합니다.

ccuse doctor 명령어는 Claude Code, Python, 프로필 및 프로젝트 설정이 제대로 구성되었는지 확인하기 때문에, 처음 사용하는 사용자나 문제 해결(troubleshooting) 시에 특히 유용하다고 설명되어 있습니다.

설치 방법 (Installation Methods)

세 가지 설치 방식이 문서화되어 있습니다:

1. 원라인 설치 (One-Line Install, 권장): 스크립트를 ~/.local/bin/ccuse로 직접 다운로드하고 실행 가능하게 만듭니다.
2. Claude Code Skill을 통한 설치: Claude Code에게 직접 요청하여 설치할 수 있습니다.
3. 수동 설치 (Manual Install): 저장소(repository)를 클론(cloning)하고 실행 파일에 대한 심볼릭 링크(symlink)를 생성하는 과정을 포함합니다.

설치 후, ccuse --help를 통해 도구가 올바르게 작동하는지 확인할 수 있습니다.

프로필 설정 워크플로 (Profile Setup Workflow)

문서화된 프로필 설정 워크플로는 다음 다섯 단계를 따릅니다:

1. ccuse doctor를 사용하여 설정 확인 (Check setup) 및 필수 요구 사항 검증
2. ccuse init-claude를 사용하여 현재 Claude 설정 저장 (Save current Claude settings) 및 네이티브 Claude 프로필 생성
3. ccuse init-ark, ccuse init-glm, ccuse init-kimi 또는 ccuse init-minimax와 같은 명령어를 사용하여 추가 프로필 생성 (Create additional profiles)
4. 자동으로 열리는 프로필 파일을 편집하여 API 키 설정 (Set API keys)
5. 각 프로필의 범위(Scope) 선택: 일회성 세션 (one-time session), 프로젝트 특정 (project-specific), 또는 전역 (global)

프로필을 생성할 때, init 명령어는 사용자가 선호하는 에디터를 사용하여 프로필 파일을 편집할 수 있도록 자동으로 엽니다 (우선순위: $EDITOR 환경 변수, VS Code code, 그 다음 nano 순).

커스텀 프로필 (Custom Profiles)

문서에 따르면 개발자는 Anthropic 호환 API를 위한 커스텀 프로필을 생성할 수 있습니다. 커스텀 프로필은 ~/.claude/profiles/에 JSON 파일로 저장되며, API 키, 베이스 URL (base URLs), 타임아웃 설정 (timeout settings) 및 기타 환경 변수 (environment variables)에 대한 구성을 포함할 수 있습니다.

프로필 명명 규칙이 지정되어 있습니다: 이름은 반드시 문자 또는 숫자로 시작해야 하며, 문자, 숫자, 마침표(.), 밑줄(_), 하이픈(-)을 포함할 수 있습니다. 내장된 명령어 및 별칭 (aliases)을 포함하여 특정 이름은 예약되어 있으므로 커스텀 프로필용으로 사용할 수 없습니다.

파일 구조 (File Structure)

이 도구는 ~/.claude/ 아래의 다음 디렉토리 구조에 프로필과 설정을 저장합니다:

• settings.json - 활성화된 전역 설정 (Active global configuration)
• settings.json.bak - 자동 백업 (Automatic backup)
• profiles/ - 개별 프로필 JSON 파일이 포함된 디렉토리

이 경로들을 커스텀 설정할 수 있는 여러 환경 변수가 제공됩니다: CLAUDE_DIR, PROFILE_DIR, SETTINGS_FILE, BACKUP_SUFFIX, PROJECT_CLAUDE_DIR, PROJECT_SETTINGS_FILE 등.

테스트 (Testing)

리포지토리에는 bats-core (Bash Automated Testing System)를 사용하는 포괄적인 테스트 스위트가 포함되어 있습니다. bats tests/test_ccuse.bats 명령어로 bats를 설치한 후 테스트를 실행할 수 있습니다.

해석 및 사용 사례 (Interpretation and Use Cases)

문서화된 기능에 기반할 때, 이 도구는 Claude Code를 정기적으로 사용하면서 수동 설정의 번거로움 없이 여러 AI API 제공업체(providers)를 실험하고자 하는 개발자들에게 가장 유용해 보입니다. 세 가지 범위(global, project, session)는 서로 다른 워크플로우(workflows)에 맞춘 유연성을 제공합니다.

서로 다른 모델 요구 사항을 가진 여러 프로젝트를 넘나들며 작업하는 개발자들에게는 프로젝트 범위(project-scoped) 프로필이 특히 유용할 수 있으며, 이를 통해 전역 설정(global configuration)에 영향을 주지 않고 각 저장소(repository)가 자체적인 기본 제공업체를 유지할 수 있습니다. 마찬가지로, 세션 수준(session-level) 전환은 동일한 작업에 대해 서로 다른 제공업체를 병행하여 테스트하는 데 적합합니다.

사용자 정의 프로필을 생성할 수 있는 능력은 이 도구가 미리 구성된 5개의 제공업체에 국한되지 않음을 의미하며, 잠재적으로 Anthropic 호환 인증을 지원하는 모든 API 엔드포인트(endpoint)로 그 유용성을 확장할 수 있습니다.

출처 (Sources)

• Repository: https://github.com/kevinten-ai/ccuse
• Verified commit: https://github.com/kevinten-ai/ccuse/commit/07adde051c787b6e3bb3585ace9a2a6080ebd7f9