tunsuy/claude-code-go

🤖 Claude Code의 Go 재구현 — 터미널 내 AI 코딩 어시스턴트

English • 简体中文 • 日本語 • 한국어 • Español • Français

파일 읽기 및 실시간 사고(thinking) 표시를 지원하는 인터랙티브 TUI

아키텍처 분석을 포함한 포괄적인 프로젝트 분석

이 프로젝트는 Anthropic의 공식 TypeScript CLI인 Claude Code를 Go 언어로 모듈별로 완전히 재구현한 것입니다. TUI, 도구 사용(tool use), 권한 시스템(permission system), 멀티 에이전트 조정(multi-agent coordination), MCP 프로토콜, 세션 관리 등 모든 핵심 기능을 포함합니다.

이 저장소의 프로덕션 코드는 단 한 줄도 사람이 작성하지 않았습니다.

아키텍처 설계, 상세 설계 문서, 병렬 구현, 코드 리뷰(code review), QA, 통합 테스트를 포함한 프로젝트 전체 과정은 구조화된 멀티 에이전트 워크플로우(multi-agent workflow) 내에서 협업하는 9개의 Claude AI 에이전트에 의해 생성되었습니다:

PM Agent → 프로젝트 계획, 마일스톤, 작업 일정 관리
Tech Lead Agent → 아키텍처 설계, 설계 문서 리뷰, 코드 리뷰
Agent-Infra → 인프라 계층 (타입, 설정, 상태, 세션)
...

각 에이전트는 격리된 Git Worktree 브랜치에서 병렬로 작업하며, 공유 코드베이스, 설계 문서 및 QA 보고서를 통해 협업했습니다. 그 결과: go test -race ./...를 통과하는 **약 7,000줄의 프로덕션 코드와 전체 테스트 스위트(test suite)**를 완성했습니다.

이는 복잡한 멀티 레이어 Go 애플리케이션이 비동기적으로 협업하는 AI 에이전트들에 의해 완전히 설계, 구현, 리뷰 및 출시될 수 있음을 보여주는 실제 사례입니다. 모든 결정 과정의 기록은 docs/project/에 남아 있습니다.

Claude Code의 Go 구현체 — 터미널에서 실행되는 에이전트형 AI 코딩 어시스턴트입니다. Claude Code는 사용자의 코드베이스를 이해하고, 도구를 실행하며, 자연스러운 대화를 통해 코드 작성, 리뷰 및 리팩터링(refactor)을 도와줍니다.

대화형 TUI (Interactive TUI)— Bubble Tea로 구축된 다기능 터미널 UI, 다크/라이트 테마 지원
에이전트 방식의 도구 사용 (Agentic tool use)— 파일 읽기/쓰기, 셸 실행, 검색 등을 수행하며, 모든 작업은 권한 계층 (permission layer)을 통해 중개됨
멀티 에이전트 조정 (Multi-agent coordination)— 병렬 작업을 위해 백그라운드 서브 에이전트 (sub-agents) 생성
MCP 지원— Model Context Protocol (MCP)을 통해 외부 도구와 연결
CLAUDE.md 메모리— 디렉터리 트리를 따라 CLAUDE.md 파일에서 프로젝트 컨텍스트를 자동으로 로드
세션 관리 (Session management)— 이전 대화 재개; 긴 히스토리를 자동으로 압축
Vim 모드— 입력 영역에서 선택 가능한 Vim 키 바인딩 (key bindings)
OAuth + API 키 인증— Anthropic OAuth로 로그인하거나 ANTHROPIC_API_KEY 제공

18개의 내장 슬래시 명령어— /help, /clear, /compact, /commit, /diff, /review, /mcp 등
스트리밍 응답 (Streaming responses)— 사고 블록 (thinking-block) 표시와 함께 실시간 토큰 스트리밍 지원

Claude Code Go는 6개의 계층으로 구성되어 있습니다:

┌─────────────────────────────────────┐
│ CLI (cmd/claude) │ cobra entry point
├─────────────────────────────────────┤
...

상세한 분석 내용은 docs/project/architecture.md를 참조하세요.

• Go 1.21 이상
• Anthropic API 키
  또는 Claude.ai 계정 (OAuth)

git clone https://github.com/tunsuy/claude-code-go.git
cd claude-code-go
make build
...

PATH에 추가:

export PATH="$PATH:$(pwd)/bin"

go install github.com/tunsuy/claude-code-go/cmd/claude@latest

# API 키 설정 (또는 OAuth 사용 — 아래 인증 섹션 참조)
export ANTHROPIC_API_KEY=sk-ant-...
# 현재 디렉터리에서 대화형 세션 시작
...

API 키 (CI/스크립트용 권장):

export ANTHROPIC_API_KEY=sk-ant-...

OAuth (대화형 사용 권장):

claude /config # 브라우저에서 OAuth 흐름을 엽니다

Claude Code Go는 여러 API 제공업체를 지원하여, Anthropic API뿐만 아니라 OpenAI 호환 API도 사용할 수 있습니다.

제공업체 (Provider)	설명 (Description)	환경 변수 (Environment Variables)
direct (기본값)	Anthropic Direct API	ANTHROPIC_API_KEY , ANTHROPIC_BASE_URL
openai	OpenAI 및 호환 가능한 API	OPENAI_API_KEY , OPENAI_BASE_URL
bedrock	AWS Bedrock	환경 변수를 통한 AWS 자격 증명
vertex	Google Cloud Vertex AI	환경 변수를 통한 GCP 자격 증명

OpenAI, DeepSeek, Qwen, Moonshot 또는 기타 OpenAI 호환 API를 사용하려면:

방법 1: 환경 변수 (Environment Variables)

# 제공업체를 openai로 설정
export CLAUDE_PROVIDER=openai
# API 키 설정
...

방법 2: 설정 파일 (Configuration File)

~/.config/claude-code/settings.json 파일을 생성하거나 편집하십시오:

{
"provider": "openai",
"apiKey": "sk-xxx",
...

OpenAI:

• 모든 GPT-4 및 GPT-3.5 모델 지원
• 완전한 도구/함수 호출 (tool/function calling) 지원
• 스트리밍 응답 (Streaming responses)

DeepSeek:

export CLAUDE_PROVIDER=openai
export OPENAI_API_KEY=sk-xxx
export OPENAI_BASE_URL=https://api.deepseek.com
...

Ollama (로컬):

export CLAUDE_PROVIDER=openai
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=llama3

Azure OpenAI:

export CLAUDE_PROVIDER=openai
export OPENAI_API_KEY=your-azure-key
export OPENAI_BASE_URL=https://your-resource.openai.azure.com
...

claude [flags]

플래그 (Flag)	설명 (Description)
--resume	가장 최근의 세션 재개
--session <id>	ID를 통해 특정 세션 재개
--model <name>	기본 Claude 모델 재정의
--dark / --light	다크 모드 또는 라이트 모드 강제 적용
--vim	Vim 키 바인딩 (key bindings) 활성화
-p, --print <prompt>	비대화형 (Non-interactive): 단일 프롬프트를 실행하고 종료

입력창에 /를 입력하면 사용 가능한 모든 명령어를 볼 수 있습니다:

명령어	설명
/help	모든 명령어 표시
/clear	대화 기록 삭제
/compact	컨텍스트 (Context) 사용량을 줄이기 위해 기록 요약
/exit	Claude Code 종료
/model	Claude 모델 전환
/theme	다크/라이트 테마 전환
/vim	Vim 모드 전환
/commit	git 커밋 메시지 생성
/review	최근 변경 사항 검토
/diff	현재 차이점 (Diff) 표시
/mcp	MCP 서버 관리
/memory	로드된 CLAUDE.md 파일 표시
/session	세션 정보 표시
/status	API/연결 상태 표시
/cost	토큰 사용량 및 예상 비용 표시

• Go 1.21+
  golangci-lint

(선택 사항, 린팅 (Linting) 용)

# 빌드 (Build)
make build
# 모든 테스트 실행
...

claude-code-go/
├── cmd/claude/ # CLI 진입점 (Entry point)
├── internal/
...

Claude Code Go는 현재 원본 TypeScript 버전과 **약 65%의 기능적 동등성 (Feature parity)**을 유지하고 있습니다. v1.0에 도달하기 위한 단계별 계획은 다음과 같습니다:

단계	버전	주요 목표	일정
1단계	v0.2.0	🔒 권한 시스템 통합, Hook 시스템 연결, 테스트 커버리지 기준 마련, CI 강화	+3주
2단계	v0.3.0	🔧 22개 도구 전체 구현 (현재 11개), 전체 CLI 하위 명령 (Subcommands), 슬래시 명령어 개선, 에이전트 도구 (Agent tool)	+3주
3단계	v0.4.0	🌐 AWS Bedrock 및 GCP Vertex 제공자, MCP WebSocket 전송, 플러그인 시스템, 기능 플래그 (Feature flags)	+4주
4단계	v0.5.0	🚀 LSP 통합, 원격/서버 모드, 음성 입력, Vim 모드, 확장 사고 (Extended Thinking), 비용 추적기 (Cost Tracker)	+4주
5단계	v1.0.0	🎯 성능 최적화 (Performance tuning), 보안 감사, 전체 문서화, 멀티 플랫폼 출시	+2주

완료 상태: ████████████░░░░░░░░ 65%
✅ 완료됨: 핵심 엔진, TUI, API 클라이언트 (Direct + OpenAI), 컨텍스트 압축 (Context compaction),
OAuth, 세션 지속성, 11개 도구, 14개 슬래시 명령어
...

📋 상세 작업 분류, 아키텍처 다이어그램 및 완료 기준은 **전체 로드맵 (Full Roadmap)**을 참조하세요.

기여를 환영합니다! Pull Request를 제출하기 전에 CONTRIBUTING.md를 읽어주시기 바랍니다.

빠른 체크리스트:

• 저장소(repo)를 Fork 하고 기능 브랜치(feature branch)를 생성하세요
• make test와 make vet이 통과하는지 확인하세요
• 새로운 기능에 대한 테스트를 작성하세요
• 기존 코드 스타일을 따르세요 (gofmt ./... 실행)
• 제공된 템플릿을 사용하여 Pull Request를 생성하세요

보안 취약점을 보고하려면 SECURITY.md를 참조하세요. 보안 버그에 대해 공개적인 GitHub Issue를 열지 마세요.

이 프로젝트는 MIT License 라이선스 하에 배포됩니다 — 자세한 내용은 LICENSE를 참조하세요.

• claude-code — 오리지널 TypeScript CLI
• anthropic-sdk-go — Anthropic API를 위한 공식 Go SDK
• Model Context Protocol — AI를 도구(tools)에 연결하기 위한 개방형 표준