Octo는 작고 유용하며, 텔레메트리 (telemetry)가 전혀 없고, 문어(cephalopod) 테마를 가진 코딩 어시스턴트입니다.
Octo는 당신의 친구입니다.

시작하기

npm install --global octofriend

그 다음:

octofriend
# 또는, 짧게:
octo

정보

Octo는 OpenAI 호환 또는 Anthropic 호환 LLM API와 함께 작동하며, 특정 모델이 막혔을 때 대화 도중에 원하는 대로 모델을 전환할 수 있게 해주는 작고 유용하며 문어 테마를 가진 코딩 어시스턴트입니다. Octo는 사용 중인 메인 코딩 모델의 도구 호출 (tool call) 및 코드 편집 실패를 자동으로 처리하기 위해, 우리가 직접 학습시켜 오픈 소스로 공개한 (1, 2) ML 모델을 선택적으로 사용할 수 있으며 (사용을 권장합니다). 이 자동 수정 (autofix) 모델은 어떤 코딩 LLM과도 함께 작동합니다. Octo는 Kimi K2.5, MiniMax M2.5, GPT-5.3, Claude 4.6과 함께 매우 잘 작동합니다 (물론 거의 모든 에이전트형 코딩 모델이 작동할 것입니다). Octo는 당신의 친구이기 때문에 당신을 돕고 싶어 합니다.

Octo는 텔레메트리 (telemetry)가 전혀 없습니다. 개인정보 보호에 집중하는 LLM 제공업체(저희의 사심을 담아 Synthetic을 추천드려도 될까요?)와 함께 Octo를 사용한다는 것은 당신의 코드가 당신의 것으로 남는다는 것을 의미합니다. 하지만 OpenAI 호환 API 제공업체, Anthropic, 또는 본인의 기기에서 실행하는 로컬 LLM과 함께 사용할 수도 있습니다.

웹 검색 활성화하기

기본적으로 Octo는 Synthetic의 비공개 데이터 보존 제로 (zero-data-retention) 검색 API를 사용하여 Octo의 웹 검색 도구를 구동하기 위해 Synthetic API 키를 찾습니다. Octo의 어디에서든 Synthetic 모델이 구성되어 있다면, Octo의 검색 도구는 그냥 작동합니다 (Just Work). Claude와 같이 Synthetic에서 호스팅되지 않는 모델조차도 Octo의 웹 검색 도구를 사용할 수 있습니다.

Synthetic의 검색 API를 사용하고 싶지는 않지만 웹 검색 도구는 여전히 사용하고 싶다면, ~/.config/octofriend/octofriend.json5에서 search 설정을 구성할 수 있습니다:

{
  // ...나머지 설정,
  search: {
...

search 도구는 다음과 같은 형식으로 구성된 URL에 대해 POST 요청을 보냅니다. 이는 Synthetic 및 Exa 모두와 호환됩니다:

{
  query: "some search query",
}

search 설정을 구성하지 않고 Synthetic API 키도 구성하지 않은 경우, Octo의 하네스(harness)는 웹 검색 도구를 자동으로 숨겨서 Octo가 이를 호출하려고 시도하지 않도록 합니다.

데모 (Demo)

Octo 샌드박싱 (Sandboxing Octo)

Octo는 내장된 Docker 지원 기능을 갖추고 있으며, 특별한 설정이나 이미지 또는 컨테이너를 수정할 필요 없이 모든 Docker 컨테이너에 연결할 수 있습니다. 이미 실행 중인 기존 컨테이너 내에서 Octo를 실행하려면(예: 이미 Docker Compose 설정을 사용 중인 경우), octo docker connect your-container-name을 실행하세요.

Octo가 Docker 이미지를 실행하고 Octo가 종료될 때 이를 닫게 하려면 다음을 실행할 수 있습니다:

# docker run 인자 앞에 --를 반드시 추가하세요!
octo docker run -- ordinary-docker-run-args

예를 들어, Alpine Linux 컨테이너 내에서 Octo를 실행하려면 다음과 같이 입력합니다:

octo docker run -- -d -i -t alpine /bin/sh

Octo의 모든 셸 명령(shell commands), 파일 시스템 수정 및 읽기는 컨테이너 내부에서 수행됩니다. 하지만 Octo는 호스트 머신을 통해 설정에 정의된 모든 MCP 서버를 계속 사용할 수 있으며(MCP 서버는 컨테이너 내부가 아닌 사용자의 머신에서 실행되고 있을 것이므로), 내장된 fetch 도구를 사용할 경우 사용자의 머신에서 HTTP 요청을 보냅니다. 따라서 wget이나 curl이 설치되어 있지 않은 임의의 컨테이너도 사용할 수 있습니다.

규칙 (Rules)

Octo는 다음과 같은 이름의 지침(instruction) 파일을 찾습니다:

• OCTO.md
• CLAUDE.md
• AGENTS.md

Octo는 발견된 파일 중 첫 번째 파일을 사용합니다. 따라서 Claude를 위한 지침과 Octo를 위한 지침을 다르게 설정하고 싶다면, OCTO.md와 CLAUDE.md를 모두 작성해 두면 됩니다. 그러면 Octo는 CLAUDE.md를 무시합니다.

Octo는 현재 디렉토리와 홈 디렉토리(홈 디렉토리 포함)까지의 모든 상위 디렉토리를 검색하여 규칙을 찾습니다. 모든 규칙 파일은 병합됩니다. 따라서 모든 곳에 적용되는 일반적인 규칙뿐만 아니라 프로젝트별 규칙도 적용하고 싶다면, 프로젝트에 OCTO.md를 추가하고 홈 디렉토리에 전역 OCTO.md를 추가하면 됩니다.

홈 디렉토리를 어지럽히고 싶지 않다면, ~/.config/octofriend/OCTO.md에 전역 규칙 파일을 추가할 수도 있습니다.

기술 (Skills)

Octo는 재사용 가능한 문맥 의존적 지침 (context-dependent instructions)을 제공하기 위해 Agent Skills 사양을 지원합니다. 예를 들어, Octo가 코드 리뷰를 수행하도록 특별한 지침을 주고 싶다면 코드 리뷰 기술 (skill) 파일을 작성할 수 있으며, Octo는 코드 리뷰를 수행해야 할 때 해당 기술을 지능적으로 로드합니다. 전체 기술 사양은 Agent Skills 웹사이트에서 확인할 수 있지만, 본질적으로는 선택적 스크립트가 포함된 태그가 달린 마크다운 (Markdown)일 뿐입니다. 다음은 사용할 수 있는 매우 간단한 코드 리뷰 기술 예시입니다:

---
name: "pr-review"
description: "Review Github pull requests"
...

우리는 다음 위치에서 기술을 자동으로 감지합니다:

• ~/.config/agents/skills: 전역 기술 정의용
• .agents/skills: Octo가 작업 중인 현재 디렉토리와 관련된 기술용. 예를 들어, 회사가 에이전트를 위한 특별한 가이드라인을 가지고 있다면, 회사의 리포지토리(repo) 내 .agents/skills 디렉토리에 이를 배포할 수 있습니다.

Octo가 기술을 검색하기를 원하는 디렉토리가 더 있다면, 다음과 같이 ~/.config/octofriend/octofriend.json5 설정 파일에 추가할 수 있습니다:

skills: {
  paths: [
    // 기술을 포함하는 디렉토리 경로 목록
...

Octo를 MCP 서버에 연결하기

Octo는 기본 기능만으로도 많은 것을 할 수 있습니다. 충분한 Bash 명령어가 있다면 거의 무엇이든 가능합니다. 하지만 MCP 서버로부터 풍부한 데이터에 접근하고 싶다면, Octo가 적절한 Bash 방식 (Bash-isms)을 만들어내기 위해 촉수를 비틀며 애쓰게 하는 대신, MCP 서버를 직접 제공하는 것이 Octo에게 큰 도움이 될 것입니다. octofriend를 처음 실행하고 나면 ~/.config/octofriend/octofriend.json5에 설정 파일이 생성됩니다. Octo를 즐겨 사용하는 MCP 서버에 연결하려면 설정 파일에 다음을 추가하세요:

mcpServers: {
  serverName: {
    command: "command-string",
...

예를 들어, Octo를 Linear 워크스페이스에 연결하려면 다음과 같이 합니다:

mcpServers: {
  linear: {
    command: "npx",
...

로컬 LLM과 함께 Octo 사용하기

상대적으로 숙련된 사용자라면, Octo를 로컬 LLM (Large Language Models)과 함께 사용하고 싶을 수도 있습니다. 이미 ollama나 llama.cpp와 같은 로컬 LLM API 서버가 설정되어 있다고 가정하면, Octo를 사용하는 방법은 매우 쉽습니다. 모델을 추가할 때 Add a custom model...을 선택하세요. 그러면 API 기본 URL (base URL)을 입력하라는 메시지가 표시되는데, 이는 아마도 http://localhost:3000이나 로컬 LLM 서버를 실행 중인 포트와 같을 것입니다. 그 다음 인증 정보로 사용할 환경 변수를 입력하라는 메시지가 나타납니다. 비어 있지 않은 아무 환경 변수나 사용하면 됩니다 (대부분의 로컬 LLM 서버는 어차피 인증 정보를 무시하기 때문입니다).

또한 ~/.config/octofriend/octofriend.json5에서 Octofriend 설정을 직접 편집할 수도 있습니다. 모델 목록에 다음을 추가하기만 하면 됩니다:

{
  nickname: "UI에 표시될 모델 이름 문자열",
  baseUrl: "http://localhost:SOME_PORT",
...

디버깅 (Debugging)

기본적으로 Octo는 매우 깔끔한 UI를 보여주려고 노력합니다. API나 도구 호출 (tool calls)에서 발생하는 근본적인 에러 메시지를 보고 싶다면, OCTO_VERBOSE 환경 변수를 truthy한 문자열로 설정하여 Octo를 실행하세요. 예를 들면 다음과 같습니다:

OCTO_VERBOSE=1 octofriend

데스크톱 알림 (Desktop notifications)

데스크톱 알림 (Desktop notifications)을 설정한 경우에만 나타나는 숨겨진 "Notifications" 메뉴가 있습니다. 데스크톱 알림을 설정하려면 octofriend.json5 파일에 다음과 같은 블록을 추가하세요:

notifications: {
  notifyCommand: "notify-send Octo 'Finished responding!'",
},

또는 macOS의 경우:

notifications: {
  notifyCommand: 'osascript -e \'display notification "Octo finished!"\'
',

이렇게 하면 메인 ctrl-p 메뉴에 Notifications 서브메뉴가 활성화됩니다. 다음과 같은 세 가지 설정으로 지정할 수 있습니다:

• Octo가 입력이 필요할 때마다 다음번에 알림 (Notify the next time Octo needs input)
• 이번 세션 동안 Octo가 입력이 필요할 때마다 알림 (Notify any time Octo needs input this session)
• Octo가 입력이 필요할 때마다 항상 알림 (Always notify any time Octo needs input)

마지막 옵션을 설정하면 해당 설정이 구성 파일 (config file)에 영구적으로 저장됩니다.

기본적으로 세션 수준 (session-level) 및 영구적 알림 (persistent notifications)의 경우, Octo는 알림을 보내기 전 10초 동안 대기하며, 그 사이에 입력을 받으면 알림을 건너뜁니다 (사용자가 활발하게 참여하여 채팅 중일 때 알림 스팸이 발생하는 것을 방지하기 위함입니다). 대기 시간을 변경하려면 다음과 같이 설정하세요:

notifications: {
  notifyCommand: "some command",
  notifyTimeoutMs: 20000, // 또는 원하는 밀리초(ms) 단위 시간
...

Canary 버전 사용하기 (Opting into canary versions)

아직 출시되지 않은 버전의 Octo를 사용하고 싶다면, 이 저장소 (repo)를 클론(clone)한 뒤 canary.sh에 있는 지침을 읽고 셸(shell)에 canary-octo를 설치하세요.