Codi (코디)

터미널에서 동작하는 AI 코딩 에이전트입니다.

파일 읽기/쓰기, 코드 검색, 셸 실행, Git 조작 등 15개 이상의 도구를 자율적으로 사용하여 소프트웨어 개발 작업을 도와줍니다.

빠른 시작

1. 설치

# Node.js 20 이상 필요
node --version  # v20.0.0+

# npm으로 설치 (추천)
npm install -g @gemdoq/codi

# 또는 설치 없이 바로 실행
npx @gemdoq/codi

# 또는 Homebrew (macOS)
brew tap gemdoq/codi
brew install codi

git clone https://github.com/gemdoq/codi.git
cd codi
npm install
npm run build
npm link  # 전역 명령어로 등록

2. API 키 설정

Codi는 기본적으로 Google Gemini 2.5 Flash (무료)를 사용합니다.

처음 실행하면 설정 마법사가 자동으로 안내합니다. 수동 설정도 가능합니다:

API 키 발급:

1. Google AI Studio 접속
2. Google 계정으로 로그인
3. "Create API Key" 클릭
4. 키 복사

설정 방법 (택 1):

# 방법 A: 환경변수 (추천 - 터미널 세션 동안 유지)
export GEMINI_API_KEY=your-api-key-here

# 방법 B: 셸 설정에 영구 등록 (zsh)
echo 'export GEMINI_API_KEY=your-api-key-here' >> ~/.zshrc
source ~/.zshrc

# 방법 C: 셸 설정에 영구 등록 (bash)
echo 'export GEMINI_API_KEY=your-api-key-here' >> ~/.bashrc
source ~/.bashrc

# 방법 D: 설정 파일
mkdir -p ~/.codi
cat > ~/.codi/settings.json << 'EOF'
{
  "apiKeys": {
    "openai": "your-api-key-here"
  }
}
EOF

3. 실행

codi

사용법

대화형 모드

codi

프롬프트(codi >)가 나타나면 자연어로 요청하면 됩니다:

codi > 이 프로젝트의 구조를 분석해줘
codi > src/main.ts에서 버그를 찾아 고쳐줘
codi > package.json에 새 스크립트를 추가해줘

단일 프롬프트 모드

codi -p "이 디렉토리의 파일 목록을 보여줘"
codi -p "README.md를 한국어로 번역해줘"

종료

exit     # 또는 quit, q
/quit    # 또는 /exit
Ctrl+D   # 즉시 종료
Ctrl+C   # 두 번 누르면 종료

CLI 옵션

| 옵션 | 설명 | |------|------| | -p <프롬프트> | 단일 프롬프트 실행 후 종료 | | -m, --model <모델> | 모델 변경 (기본: gemini-2.5-flash) | | --provider <이름> | 프로바이더 변경 (openai, anthropic, ollama) | | -c, --continue | 마지막 세션 이어하기 | | -r, --resume <id> | 특정 세션 복원 | | --plan | 플랜 모드 (읽기 전용 분석) | | --yolo | 모든 권한 확인 건너뛰기 | | -h, --help | 도움말 | | -v, --version | 버전 표시 |

입력 특수 기능

| 입력 | 기능 | |------|------| | \ + Enter | 멀티라인 입력 | | !ls -la | 직접 셸 명령어 실행 | | @src/main.ts | 파일 내용을 메시지에 첨부 | | /help | 슬래시 커맨드 목록 |

슬래시 커맨드

대화 중 /로 시작하는 커맨드를 사용할 수 있습니다:

| 커맨드 | 설명 | |--------|------| | /help | 사용 가능한 커맨드 목록 | | /quit /exit | 종료 | | /clear /reset /new | 대화 초기화 | | /model [이름] | 모델 전환 | | /compact [초점] | 대화 압축 (컨텍스트 절약) | | /cost | 토큰 사용량 및 비용 표시 | | /config | 현재 설정 표시 | | /permissions | 권한 규칙 확인 | | /save [이름] | 세션 저장 | | /resume /continue | 세션 복원 | | /fork [이름] | 대화 분기 | | /plan | 플랜 모드 전환 (읽기 전용) | | /memory | 자동 메모리 확인/편집 | | /init | CODI.md 초기화 | | /export [파일] | 대화 내보내기 | | /tasks | 태스크 목록 | | /status | 시스템 상태 | | /context | 컨텍스트 윈도우 사용량 | | /rewind | 이전 체크포인트로 되감기 | | /diff | 변경사항 diff | | /mcp | MCP 서버 상태 |

지원 모델

Google Gemini (기본)

export GEMINI_API_KEY=your-key
codi                                  # gemini-2.5-flash (기본)
codi --model gemini-2.5-pro           # 더 강력한 모델

Anthropic Claude

export ANTHROPIC_API_KEY=your-key
codi --provider anthropic                                   # claude-sonnet
codi --provider anthropic --model claude-opus-4-20250514    # claude-opus

OpenAI

export OPENAI_API_KEY=your-key
codi --provider openai --model gpt-4o
codi --provider openai --model gpt-4.1

Ollama (로컬, 무료)

# Ollama 설치 후 모델 다운로드
ollama pull llama3.1

codi --provider ollama --model llama3.1

내장 도구

Codi는 다음 도구를 자동으로 사용합니다. 사용자가 도구를 직접 호출할 필요 없이, 자연어로 요청하면 적절한 도구를 선택합니다.

| 도구 | 기능 | 예시 요청 | |------|------|----------| | read_file | 파일 읽기 (텍스트, PDF, 이미지, .ipynb) | "main.ts 파일을 읽어줘" | | write_file | 파일 생성 | "hello.py 파일을 만들어줘" | | edit_file | 파일 수정 (정확한 문자열 치환) | "함수 이름을 바꿔줘" | | multi_edit | 한 파일 다중 수정 | "이 파일에서 여러 곳을 고쳐줘" | | glob | 파일 패턴 검색 | "모든 .ts 파일을 찾아줘" | | grep | 코드 내용 검색 (정규식) | "TODO가 있는 파일을 찾아줘" | | bash | 셸 명령어 실행 | "테스트를 실행해줘" | | list_dir | 디렉토리 목록 | "src 폴더 안에 뭐가 있어?" | | git | Git 작업 | "변경사항을 커밋해줘" | | web_fetch | 웹 페이지 가져오기 | "이 URL의 내용을 요약해줘" | | web_search | 웹 검색 | "React 18 새 기능을 검색해줘" | | notebook_edit | Jupyter 노트북 편집 | "노트북에 셀을 추가해줘" | | sub_agent | 서브 에이전트 실행 | "이 코드베이스를 분석해줘" | | task_* | 태스크 관리 | "할 일 목록을 만들어줘" | | ask_user | 사용자에게 질문 | (자동으로 확인이 필요할 때 사용) |

권한 시스템

파일 수정, 셸 실행 등 위험한 작업은 실행 전에 확인을 요청합니다:

⚠ Permission Required: bash
  command: npm install express
Allow? [Yes / no / always for this tool]

• Y 또는 Enter: 이번만 허용
• n: 거부
• a: 이 도구는 앞으로 묻지 않고 항상 허용

권한 규칙 설정

~/.codi/settings.json 또는 .codi/settings.json에서 설정:

{
  "permissions": {
    "allow": ["read_file", "glob", "grep", "list_dir"],
    "deny": ["bash(rm -rf *)"],
    "ask": ["write_file", "edit_file", "bash"]
  }
}

프로젝트 설정 (CODI.md)

프로젝트 루트에 CODI.md 파일을 만들면 Codi가 프로젝트 컨텍스트를 자동으로 인식합니다:

codi
codi > /init  # CODI.md 템플릿 생성

# 프로젝트: My App

## 개요
React + TypeScript 웹 애플리케이션

## 개발 규칙
- 컴포넌트는 함수형으로 작성
- CSS는 Tailwind 사용
- 테스트는 Vitest 사용

## 빌드 명령어
- `npm run dev`: 개발 서버
- `npm run build`: 프로덕션 빌드
- `npm test`: 테스트 실행

커스텀 슬래시 커맨드

자주 쓰는 프롬프트를 커맨드로 저장할 수 있습니다:

# 프로젝트용 커맨드
mkdir -p .codi/commands
cat > .codi/commands/review.md << 'EOF'
현재 git diff를 확인하고 코드 리뷰를 해주세요.
보안 취약점, 성능 이슈, 코드 스타일 문제를 중심으로 검토해주세요.
EOF

# 개인 전역 커맨드
mkdir -p ~/.codi/commands
cat > ~/.codi/commands/fix.md << 'EOF'
{{file_path}} 파일의 lint 에러를 모두 수정해주세요.
EOF

사용: /review, /fix src/main.ts

MCP (Model Context Protocol) 연동

외부 도구를 MCP 서버로 연결할 수 있습니다:

cat > .codi/mcp.json << 'EOF'
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}
EOF

훅 시스템

도구 실행 전후에 자동으로 스크립트를 실행할 수 있습니다:

// .codi/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "edit_file",
      "hooks": [{
        "type": "command",
        "command": "npx eslint --fix ${file_path}"
      }]
    }]
  }
}

설정 파일

설정은 다음 순서로 병합됩니다 (아래가 우선순위 높음):

1. ~/.codi/settings.json - 사용자 전역
2. .codi/settings.json - 프로젝트 (Git에 포함)
3. .codi/settings.local.json - 로컬 전용 (.gitignore에 추가 권장)

{
  "provider": "openai",
  "model": "gemini-2.5-flash",
  "maxTokens": 8192,
  "apiKeys": {
    "openai": "your-gemini-key"
  },
  "permissions": {
    "allow": ["read_file", "glob", "grep"],
    "deny": [],
    "ask": ["bash", "write_file"]
  }
}

키보드 단축키

| 단축키 | 기능 | |--------|------| | Ctrl+C | 현재 작업 취소 (두 번 누르면 종료) | | Ctrl+D | 즉시 종료 | | Ctrl+L | 화면 지우기 | | Tab | 자동 완성 (커맨드, 파일 경로) |

요구사항

• Node.js 20.0.0 이상
• ripgrep (rg) - 코드 검색 성능 향상 (선택, 없으면 grep 사용)
• Git - Git 관련 기능 사용 시 필요

배포 (메인테이너용)

새 버전을 배포하는 방법입니다. 터미널에서 아래 두 줄만 실행하면 됩니다.

버전 종류

| 명령어 | 변화 | 언제 쓰나 | |--------|------|----------| | npm version patch | 0.1.1 → 0.1.2 | 버그 수정 | | npm version minor | 0.1.1 → 0.2.0 | 새 기능 추가 | | npm version major | 0.1.1 → 1.0.0 | 큰 변경 (호환 깨질 때) |

전체 흐름 (예시)

예를 들어 "슬래시 커맨드 /version을 추가"하는 작업을 했다면:

# ① 평소처럼 코드를 수정하고 커밋한다 (여기까지는 항상 하던 것과 동일)
git add src/config/slash-commands.ts
git commit -m "feat: add /version slash command"

# 필요하면 커밋을 여러 번 해도 된다
git add src/ui/renderer.ts
git commit -m "fix: fix rendering bug"

# ② 작업이 다 끝나면, 버전을 올린다
npm version patch

# ③ GitHub에 올린다 (이러면 자동으로 npm 배포 + Homebrew 업데이트됨)
git push origin main --tags

npm version patch는 내부적으로 이 세 가지를 한번에 해주는 단축 명령어입니다:

1. package.json의 "version": "0.1.1" → "0.1.2"로 수정
2. 자동으로 git commit
3. 자동으로 git tag v0.1.2 (이 커밋에 버전 이름표 부착)

그래서 흐름을 정리하면:

[평소 작업]                           [배포]

코드 수정 → git commit               npm version patch → git push origin main --tags
코드 수정 → git commit                     ↓
코드 수정 → git commit               GitHub Actions 자동 실행
    ↓                                      ↓
여기까지는 평소랑 똑같음              npm 배포 + Homebrew 업데이트

배포 절차 (요약)

cd ~/codi
npm version patch                  # 버전업 + 자동 커밋 + 자동 태그
git push origin main --tags        # push하면 자동 배포

이게 끝입니다. GitHub Actions가 자동으로:

1. 테스트 실행
2. npm에 새 버전 배포
3. Homebrew Formula 업데이트

배포 확인

# npm에 올라갔는지 확인
npm info @gemdoq/codi version

# GitHub Actions 탭에서 워크플로우 성공 여부 확인
# https://github.com/gemdoq/codi/actions

사전 준비 (최초 1회만)

배포 자동화를 위해 GitHub Secrets에 두 개의 토큰이 등록되어 있어야 합니다:

| Secret 이름 | 용도 | 발급 위치 | |-------------|------|----------| | NPM_TOKEN | npm 배포 인증 | https://www.npmjs.com/settings/gemdoq/tokens | | HOMEBREW_GITHUB_TOKEN | Homebrew Formula 자동 업데이트 | https://github.com/settings/tokens |

등록 위치: https://github.com/gemdoq/codi/settings/secrets/actions

문제 해결

"Could not resolve authentication method" 에러

API 키가 설정되지 않았습니다. API 키 설정 섹션을 참고하세요.

"429 Rate Limit" 에러

API 요청 한도를 초과했습니다. 잠시 후 다시 시도하거나, Google AI Studio에서 할당량을 확인하세요.

ripgrep이 없다는 경고

grep 도구가 시스템 grep으로 대체됩니다. 성능 향상을 위해 설치를 권장합니다:

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

라이선스

MIT