Crush: 터미널 기반 AI 코딩 에이전트 완전 정복 가이드

⏱️ 예상 읽기 시간: 12분

서론

현대 개발 환경에서 AI 코딩 어시스턴트는 더 이상 선택이 아닌 필수가 되었습니다. Crush는 Charm Bracelet에서 개발한 터미널 기반 AI 코딩 에이전트로, 개발자들이 친숙한 터미널 환경에서 직접 AI와 상호작용할 수 있게 해줍니다.

이 가이드에서는 Crush의 설치부터 고급 설정까지 macOS 환경에서 실제 테스트한 결과와 함께 상세히 다루겠습니다.

Crush의 주요 특징

• 🤖 다양한 AI 모델 지원: OpenAI, Anthropic, Groq, Google Gemini 등
• 🔧 LSP 통합: 언어 서버 프로토콜을 통한 정확한 코드 분석
• 🌐 MCP 지원: Model Context Protocol을 통한 확장성
• ⚡ 터미널 네이티브: 익숙한 CLI 환경에서 자연스러운 사용
• 🛡️ 안전한 실행: 도구 실행 전 권한 확인 시스템

환경 요구사항

macOS 테스트 환경

이 튜토리얼은 다음 환경에서 테스트되었습니다:

# 테스트 환경 정보
OS: macOS (Apple Silicon)
아키텍처: arm64
Go 버전: go1.21+
Homebrew: 설치 필요

필요한 API 키

Crush를 사용하려면 다음 중 하나 이상의 API 키가 필요합니다:

• OpenAI API Key: GPT 모델 사용
• Anthropic API Key: Claude 모델 사용
• Groq API Key: 빠른 추론 속도
• Google API Key: Gemini 모델 사용

설치 가이드

1. Homebrew를 통한 설치 (권장)

macOS에서 가장 간편한 설치 방법입니다:

# Charm Bracelet tap 추가
brew tap charmbracelet/tap

# Crush 설치
brew install crush

# 설치 확인
crush --version

실제 테스트 결과:

➜ crush --version
crush version v0.1.11

2. 대안 설치 방법

Go를 통한 설치

go install github.com/charmbracelet/crush@latest

직접 바이너리 다운로드

GitHub 릴리즈 페이지에서 플랫폼별 바이너리를 다운로드할 수 있습니다.

기본 사용법

첫 실행 및 설정

# 대화형 모드 시작
crush

# 특정 디렉토리에서 실행
crush -c /path/to/project

# 디버그 모드로 실행
crush -d

단일 프롬프트 실행

# 간단한 질문
crush run "이 코드를 리뷰해주세요"

# 파일 분석 요청
crush run "main.py 파일의 성능을 개선할 방법을 제안해주세요"

API 키 설정

환경 변수로 API 키를 설정합니다:

# OpenAI
export OPENAI_API_KEY="your-openai-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# Groq
export GROQ_API_KEY="your-groq-api-key"

# Google Gemini
export GEMINI_API_KEY="your-gemini-api-key"

설정 파일 구성

기본 설정 파일

Crush는 다음 순서로 설정 파일을 찾습니다:

1. ./.crush.json (프로젝트 로컬)
2. ./crush.json (프로젝트 루트)
3. $HOME/.config/crush/crush.json (전역)

기본 설정 예제

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": false,
    "debug_lsp": false
  },
  "permissions": {
    "allowed_tools": [
      "view",
      "ls", 
      "grep",
      "edit"
    ]
  }
}

LSP 통합 설정

Language Server Protocol을 통해 더 정확한 코드 분석이 가능합니다:

{
  "$schema": "https://charm.land/crush.json",
  "lsp": {
    "go": {
      "command": "gopls"
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": {
      "command": "pylsp"
    },
    "rust": {
      "command": "rust-analyzer"
    }
  }
}

MCP 서버 연동

Model Context Protocol을 통한 확장 기능:

{
  "$schema": "https://charm.land/crush.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github": {
      "type": "http", 
      "url": "https://api.github.com/mcp/",
      "headers": {
        "Authorization": "$(echo Bearer $GITHUB_TOKEN)"
      }
    }
  }
}

고급 설정

커스텀 AI 프로바이더

OpenAI 호환 API를 사용하는 경우:

{
  "$schema": "https://charm.land/crush.json",
  "providers": {
    "deepseek": {
      "type": "openai",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "Deepseek V3",
          "cost_per_1m_in": 0.27,
          "cost_per_1m_out": 1.1,
          "context_window": 64000,
          "default_max_tokens": 5000
        }
      ]
    }
  }
}

권한 관리

보안을 위한 도구 실행 권한 설정:

{
  "$schema": "https://charm.land/crush.json",
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep", 
      "edit",
      "mcp_context7_get-library-doc"
    ]
  }
}

주의: --yolo 플래그는 모든 권한 확인을 건너뛰므로 매우 신중하게 사용해야 합니다.

실제 테스트 결과

테스트 환경 구성

# 테스트 디렉토리 생성
mkdir crush-test && cd crush-test

# 샘플 Python 파일 생성  
cat > main.py << 'EOF'
def fibonacci(n):
    """피보나치 수열을 계산하는 함수"""
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

def main():
    """메인 함수"""
    n = 10
    print(f"피보나치({n}) = {fibonacci(n)}")

if __name__ == "__main__":
    main()
EOF

설정 파일 생성

cat > .crush.json << 'EOF'
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": false
  },
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep"
    ]
  }
}
EOF

명령어 테스트

# 도움말 확인
crush --help

# 버전 확인  
crush --version  # crush version v0.1.11

# 로그 확인
crush logs --help

로깅 및 디버깅

로그 파일 위치

Crush는 프로젝트별로 로그를 저장합니다:

# 로그 파일 위치
./.crush/logs/crush.log

로그 확인 명령어

# 최근 1000줄 출력
crush logs

# 최근 500줄 출력
crush logs --tail 500

# 실시간 로그 확인
crush logs --follow

디버그 모드

# 디버그 모드로 실행
crush -d

# LSP 디버그 포함
crush -d --debug-lsp

설정 파일에서도 디버그 모드를 활성화할 수 있습니다:

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": true,
    "debug_lsp": true
  }
}

zshrc 별칭 설정

효율적인 사용을 위한 별칭 설정:

# ~/.zshrc에 추가
alias cr="crush"
alias crd="crush -d"
alias crl="crush logs"
alias crr="crush run"

# 프로젝트별 실행
alias crp="crush -c"

# 로그 관련
alias crlog="crush logs --follow"
alias crtail="crush logs --tail"

# 설정 파일 편집
alias credit="code .crush.json"

함수 형태의 고급 별칭

# ~/.zshrc에 추가

# 특정 디렉토리에서 Crush 실행
function crush-project() {
    local project_dir="$1"
    if [ -z "$project_dir" ]; then
        echo "사용법: crush-project <directory>"
        return 1
    fi
    crush -c "$project_dir"
}

# 빠른 코드 리뷰
function crush-review() {
    local file="$1"
    if [ -z "$file" ]; then
        echo "사용법: crush-review <filename>"
        return 1
    fi
    crush run "이 파일을 리뷰해주세요: $file"
}

# 설정 파일 생성
function crush-init() {
    cat > .crush.json << 'EOF'
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": false
  },
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit"
    ]
  }
}
EOF
    echo "✅ .crush.json 파일이 생성되었습니다."
}

실용적인 사용 사례

1. 코드 리뷰 및 개선

# 파일 분석
crush run "main.py 파일의 성능 문제를 찾아주세요"

# 코드 스타일 검사
crush run "이 프로젝트의 코딩 스타일을 통일해주세요"

2. 버그 디버깅

# 에러 분석
crush run "이 에러 로그를 분석해주세요: $(cat error.log)"

# 테스트 케이스 생성
crush run "이 함수에 대한 단위 테스트를 작성해주세요"

3. 문서화

# README 생성
crush run "이 프로젝트에 대한 README.md를 작성해주세요"

# API 문서 생성
crush run "이 함수들에 대한 API 문서를 생성해주세요"

4. 리팩토링

# 코드 구조 개선
crush run "이 코드를 더 읽기 쉽게 리팩토링해주세요"

# 디자인 패턴 적용
crush run "이 코드에 적절한 디자인 패턴을 적용해주세요"

트러블슈팅

일반적인 문제들

1. API 키 오류

Error: No API key found for any provider

해결책:

# 환경 변수 확인
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# API 키 재설정
export OPENAI_API_KEY="your-key-here"

2. LSP 연결 실패

Warning: Failed to start LSP server for language: go

해결책:

# LSP 서버 설치 확인
which gopls
which typescript-language-server

# Go의 경우 gopls 설치
go install golang.org/x/tools/gopls@latest

3. 권한 오류

Permission denied: tool execution not allowed

해결책: 설정 파일에서 허용된 도구 목록을 확인하고 업데이트:

{
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit",
      "run"
    ]
  }
}

성능 최적화

1. 대용량 프로젝트에서의 성능

{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "max_file_size": "1MB",
    "exclude_patterns": [
      "node_modules/*",
      ".git/*",
      "dist/*",
      "build/*"
    ]
  }
}

2. 메모리 사용량 제한

# 가벼운 모드로 실행
crush run --max-tokens 1000 "간단한 질문"

보안 고려사항

1. API 키 관리

# 환경 변수 파일 사용 (.env)
echo "OPENAI_API_KEY=your-key" > .env
echo ".env" >> .gitignore

# 보안 도구로 키 관리
brew install sops  # 암호화된 설정 관리

2. 도구 실행 제한

{
  "$schema": "https://charm.land/crush.json",
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep"
    ],
    "blocked_tools": [
      "rm",
      "delete", 
      "exec"
    ]
  }
}

3. 네트워크 보안

{
  "$schema": "https://charm.land/crush.json",
  "security": {
    "allowed_domains": [
      "api.openai.com",
      "api.anthropic.com"
    ],
    "proxy": "http://proxy.company.com:8080"
  }
}

테스트 자동화 스크립트

완전한 테스트 환경을 구성하는 스크립트:

#!/bin/bash
# 파일: test-crush-setup.sh

echo "🤖 Crush AI Coding Agent 종합 테스트"
echo "======================================="

# 1. 환경 확인
echo "1. 환경 정보"
echo "   OS: $(uname -s)"
echo "   아키텍처: $(uname -m)" 
echo "   Crush 버전: $(crush --version 2>/dev/null || echo 'Not installed')"
echo ""

# 2. 의존성 확인
echo "2. 의존성 확인"
command -v brew >/dev/null && echo "   ✅ Homebrew 설치됨" || echo "   ❌ Homebrew 필요"
command -v go >/dev/null && echo "   ✅ Go 설치됨: $(go version)" || echo "   ⚠️  Go 선택사항"
echo ""

# 3. 설치 테스트
if ! command -v crush >/dev/null; then
    echo "3. Crush 설치"
    echo "   다음 명령어로 설치하세요:"
    echo "   brew tap charmbracelet/tap && brew install crush"
    exit 1
fi

# 4. 테스트 프로젝트 구성
echo "4. 테스트 프로젝트 구성"
mkdir -p crush-test-project
cd crush-test-project

# 샘플 파일들 생성
cat > calculator.py << 'EOF'
"""간단한 계산기 모듈"""

def add(a, b):
    """두 수를 더합니다"""
    return a + b

def multiply(a, b):
    """두 수를 곱합니다"""  
    return a * b

def divide(a, b):
    """두 수를 나눕니다"""
    if b == 0:
        raise ValueError("0으로 나눌 수 없습니다")
    return a / b

class Calculator:
    """계산기 클래스"""
    
    def __init__(self):
        self.history = []
    
    def calculate(self, operation, a, b):
        """계산을 수행하고 히스토리에 저장"""
        if operation == 'add':
            result = add(a, b)
        elif operation == 'multiply':
            result = multiply(a, b)
        elif operation == 'divide':
            result = divide(a, b)
        else:
            raise ValueError(f"지원하지 않는 연산: {operation}")
        
        self.history.append(f"{operation}({a}, {b}) = {result}")
        return result
EOF

cat > main.py << 'EOF'
"""메인 실행 파일"""
from calculator import Calculator

def main():
    calc = Calculator()
    
    # 계산 예제
    print("=== 계산기 테스트 ===")
    print(f"5 + 3 = {calc.calculate('add', 5, 3)}")
    print(f"4 * 7 = {calc.calculate('multiply', 4, 7)}")
    print(f"10 / 2 = {calc.calculate('divide', 10, 2)}")
    
    print("\n=== 계산 히스토리 ===")
    for entry in calc.history:
        print(entry)

if __name__ == "__main__":
    main()
EOF

# 설정 파일 생성
cat > .crush.json << 'EOF'
{
  "$schema": "https://charm.land/crush.json",
  "options": {
    "debug": false
  },
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit"
    ]
  },
  "lsp": {
    "python": {
      "command": "pylsp"
    }
  }
}
EOF

echo "   ✅ 테스트 파일 생성 완료"
echo "   ✅ 설정 파일 생성 완료"
echo ""

# 5. 사용 가이드
echo "5. 사용 가이드"
echo "   🔑 API 키 설정 (필수):"
echo "      export OPENAI_API_KEY='your-key'"
echo "      export ANTHROPIC_API_KEY='your-key'"
echo ""
echo "   🚀 Crush 실행 예제:"
echo "      crush run \"calculator.py 파일을 리뷰해주세요\""
echo "      crush run \"이 코드에 단위 테스트를 추가해주세요\""
echo "      crush run \"main.py를 더 견고하게 만들어주세요\""
echo ""
echo "   🎯 대화형 모드:"
echo "      crush"
echo ""

echo "✅ Crush 테스트 환경 구성 완료!"
echo "💡 API 키를 설정한 후 위의 명령어들을 시도해보세요."

결론

Crush는 터미널 환경에서 AI의 도움을 받아 코딩할 수 있는 강력한 도구입니다. 특히 다음과 같은 장점들이 있습니다:

주요 장점

1. 터미널 네이티브: 개발자들이 익숙한 CLI 환경
2. 다양한 AI 모델: 여러 프로바이더 지원으로 선택의 폭이 넓음
3. LSP 통합: 정확한 코드 분석과 컨텍스트 이해
4. 확장성: MCP를 통한 무한한 확장 가능성
5. 보안: 도구 실행 전 권한 확인 시스템

추천 사용 시나리오

• 코드 리뷰 및 개선: 기존 코드의 품질 향상
• 버그 디버깅: 오류 분석 및 해결책 제시
• 리팩토링: 코드 구조 개선 및 최적화
• 문서화: 자동 문서 생성 및 주석 추가
• 학습: 새로운 기술이나 패턴 학습

다음 단계

1. API 키 발급: 선호하는 AI 프로바이더에서 키 발급
2. 프로젝트별 설정: 각 프로젝트에 맞는 .crush.json 구성
3. LSP 서버 설치: 사용하는 언어의 LSP 서버 설치
4. 워크플로우 통합: 기존 개발 워크플로우에 Crush 통합

Crush는 아직 비교적 새로운 도구이지만, Charm Bracelet의 다른 도구들과 마찬가지로 빠르게 발전하고 있습니다. 터미널에서 AI와 함께 코딩하는 새로운 경험을 원한다면 Crush를 적극 추천합니다.

참고 자료

• 공식 저장소: https://github.com/charmbracelet/crush
• Charm Bracelet: https://charm.sh
• Catwalk 모델 저장소: AI 모델 정보 커뮤니티 저장소
• MCP 문서: Model Context Protocol 공식 문서

이 가이드가 Crush를 시작하는 데 도움이 되기를 바랍니다. 터미널에서 AI와 함께하는 새로운 코딩 경험을 즐겨보세요! 🚀