Goose 사용법: Block이 만든 오픈소스 AI 코딩 에이전트

AI 코딩 에이전트 시장이 점점 뜨거워지고 있죠. Claude Code나 OpenCode 같은 도구가 이미 많은 개발자의 워크플로우에 자리 잡았는데요, 오늘은 조금 다른 접근 방식을 취하는 도구를 하나 소개해드리겠습니다.

바로 Block(구 Square)이 만든 오픈소스 AI 에이전트, goose입니다. 공식 문서와 저장소에서는 이름을 소문자로 쓰기 때문에 이 글에서도 goose라고 적겠습니다.

goose는 2025년 1월에 처음 공개됐고, 같은 해 12월 Linux Foundation이 Agentic AI Foundation(AAIF)을 출범시킬 때 MCP, AGENTS.md와 함께 창립 프로젝트로 기증됐습니다. 그래서 지금은 GitHub 저장소도 block/goose에서 aaif-goose/goose로 옮겨졌고, 문서 주소도 goose-docs.ai로 바뀌었어요. 옛 주소로 접속해도 새 주소로 넘어가긴 하지만, 설치 스크립트 같은 명령어는 새 주소로 바꿔 두는 게 좋습니다.

goose가 다른 점

goose의 가장 큰 특징은 특정 LLM에 종속되지 않는다는 점입니다. Claude Code는 당연히 Claude 모델만 사용하고, 대부분의 코딩 에이전트도 특정 모델에 최적화되어 있는데요. goose는 수십 가지 LLM 제공자를 지원합니다. Anthropic의 Claude, OpenAI의 GPT, Google의 Gemini 같은 클라우드 모델은 물론이고 Ollama나 LM Studio로 돌리는 로컬 모델까지 자유롭게 선택할 수 있습니다. Claude Code나 Codex 구독이 있다면 API 키 대신 ACP로 해당 에이전트를 제공자처럼 불러다 쓸 수도 있어요.

그리고 goose 자체는 Apache 2.0 라이선스로 완전 무료입니다. 클라우드 모델을 사용하면 해당 제공자의 API 비용은 들지만 Ollama 같은 로컬 모델을 사용하면 정말 공짜로 쓸 수 있죠.

또 하나 주목할 점은 MCP(Model Context Protocol)를 처음부터 핵심에 놓고 설계되었다는 겁니다. goose의 확장(Extension)은 곧 MCP 서버이기 때문에, MCP 생태계에 있는 수천 개의 서버를 그대로 가져다 쓸 수 있습니다.

설치

goose는 macOS, Linux, Windows 모두에서 사용할 수 있고, 터미널용 CLI와 데스크톱 앱 두 가지로 제공됩니다.

Linux와 macOS에서는 설치 스크립트 한 줄이면 CLI가 설치됩니다. Windows에서도 Git Bash나 MSYS2라면 같은 명령어를 쓰면 돼요.

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

Homebrew를 쓴다면 다음과 같이 설치할 수도 있습니다.

brew install block-goose-cli

Windows PowerShell에서는 설치 스크립트를 내려받아 실행합니다.

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"; .\download_cli.ps1

데스크톱 앱은 GitHub 릴리스 페이지에서 내려받거나, macOS라면 brew install --cask block-goose로 설치하면 됩니다. 이미 CLI를 설치해 두었다면 goose update로 최신 버전으로 올릴 수 있어요.

초기 설정

설치가 끝나면 먼저 LLM 제공자를 설정해야 합니다.

goose configure

처음 실행하면 OpenRouter나 Tetrate Agent Router Service 계정으로 로그인해서 모델을 자동으로 설정할지, 제공자를 직접 고를지 묻습니다. 이미 설정을 마친 뒤에 다시 실행하면 다음과 같은 메뉴가 나타나요.

설정 메뉴

? What would you like to configure?
❯ Configure Providers
  Custom Providers
  Add Extension
  Toggle Extensions
  Remove Extension
  goose settings

“Configure Providers”를 선택하면 사용할 LLM 제공자를 고를 수 있습니다. Anthropic, OpenAI, Google, Amazon Bedrock, Azure OpenAI 같은 클라우드 서비스부터 Ollama 같은 로컬 제공자까지 선택지가 넓습니다. “Custom Providers”에서는 OpenAI나 Anthropic, Ollama와 호환되는 API를 제공하는 서비스를 직접 제공자로 등록할 수 있어요.

제공자를 선택하고 API 키를 입력하면 기본 설정이 완료됩니다. 설정은 ~/.config/goose/config.yaml 파일에 저장되어 모든 세션에서 공유됩니다.

~/.config/goose/config.yaml

GOOSE_PROVIDER: anthropic
GOOSE_MODEL: claude-sonnet-5
extensions:
  developer:
    enabled: true
    name: developer
    type: builtin

설정이 제대로 됐는지 헷갈린다면 goose doctor를 실행해 보세요. 제공자 연결과 설정 상태를 한 번에 점검해 줍니다.

세션 시작하기

설정이 끝났으면 프로젝트 디렉토리에서 세션을 시작해봅시다.

goose session

이 명령어를 실행하면 대화형 세션이 시작되고, goose가 현재 디렉토리를 작업 컨텍스트로 인식합니다. 이제 “이 프로젝트의 구조를 분석하고 README를 작성해줘”처럼 자연어로 원하는 작업을 요청하면 됩니다.

goose는 파일을 읽고 코드를 실행하고 명령어를 수행하고 파일을 수정하는 것까지 자율적으로 처리합니다. 단순히 코드를 제안하는 게 아니라 실제로 행동하는 에이전트인 거죠.

세션 관리를 위한 명령어도 몇 가지 알아두면 좋습니다.

# 마지막 세션 이어서 하기
goose session -r

# 이름을 지정해서 새 세션 시작
goose session -n my-feature

# 특정 세션 이어서 하기
goose session -r -n my-feature

# 기존 세션의 대화를 복사해서 새 세션으로 갈라지기
goose session -r -n my-feature --fork

# 저장된 세션 목록 보기
goose session list

goose session import로 Claude Code나 Codex의 .jsonl 대화 기록을 가져와 goose 세션으로 이어 갈 수도 있어요.

터미널 창마다 세션을 하나씩 붙여 두고 싶다면 goose term을 써 보세요. 셸 설정에 초기화 스크립트를 한 번 넣어 두면, 터미널 창마다 자기 세션을 유지하면서 @goose "질문"처럼 바로 물어볼 수 있습니다.

~/.zshrc

eval "$(goose term init zsh)"

비대화형 실행

항상 대화형으로 사용할 필요는 없습니다. goose run 명령어를 사용하면 작업을 지시하고 결과만 받아볼 수 있습니다.

# 텍스트로 직접 지시
goose run -t "프로젝트의 모든 TODO 주석을 찾아서 목록으로 정리해줘"

# 파일에서 지시사항 읽기
goose run -i instructions.md

# 파이프로 전달
echo "테스트를 실행하고 실패한 것만 알려줘" | goose run -i -

CI/CD 파이프라인에서 활용하거나, 쉘 스크립트의 일부로 goose를 끼워넣을 때 유용합니다. --no-session 옵션을 추가하면 세션 파일도 생성하지 않아서 깔끔하고, -q를 붙이면 진행 상황은 빼고 모델의 응답만 출력합니다. 결과를 다른 프로그램에서 파싱해야 한다면 --output-format json이나 stream-json을 쓰면 돼요.

goose run --no-session -q -t "이 코드에 보안 취약점이 있는지 검사해줘"

모델을 임시로 바꿔서 실행하고 싶을 때도 있겠죠?

goose run --provider anthropic --model claude-sonnet-5 -t "이 함수를 리팩토링해줘"

ACP 제공자로 Claude Code와 Codex 구독 쓰기

예전에는 Claude Code나 Codex를 goose의 제공자로 쓰려면 claude-code나 codex 같은 CLI 제공자를 골랐습니다. goose가 각 CLI를 직접 실행하고 그 출력을 읽어 오는 방식이었죠. 이 CLI 제공자들은 이제 사용 중단(deprecated)되었고, ACP(Agent Client Protocol)로 연결하는 ACP 제공자로 대체됐습니다.

ACP는 에디터 같은 클라이언트와 코딩 에이전트가 JSON-RPC 메시지로 대화하는 표준 프로토콜인데요. goose가 클라이언트가 되어 Claude Code나 Codex를 에이전트로 띄우고, 도구 호출이나 권한 요청 같은 정보를 구조화된 메시지로 주고받습니다. 토큰 단위로 과금되는 API 키 대신 이미 결제 중인 Claude Code나 ChatGPT 구독을 그대로 쓸 수 있다는 게 가장 큰 장점이에요.

Claude Code를 쓰려면 먼저 ACP 어댑터를 전역으로 설치하고, 터미널에서 claude를 실행해 로그인이 되어 있는지 확인합니다.

bun add -g @agentclientprotocol/claude-agent-acp

npm을 쓴다면 다음과 같이 설치합니다.

npm install -g @agentclientprotocol/claude-agent-acp

그다음 제공자를 claude-acp로 지정하면 됩니다. goose configure의 “Configure Providers”에서 골라도 되고, 환경 변수로 지정해도 돼요.

export GOOSE_PROVIDER=claude-acp
export GOOSE_MODEL=sonnet
goose session

GOOSE_MODEL에는 default(Opus), sonnet, haiku를 쓸 수 있습니다. 데스크톱 앱이라면 제공자 설정 화면에서 “Claude Code ACP”를 고르면 되는데, 어댑터가 없으면 “ACP adapter not found”라는 안내가 뜹니다. 어댑터를 설치한 뒤 “Check again”을 누르면 다시 찾아요.

Codex도 방법은 같습니다. @agentclientprotocol/codex-acp를 설치하고 codex로 로그인한 뒤, GOOSE_PROVIDER=codex-acp와 GOOSE_MODEL=current로 지정하면 됩니다.

goose의 권한 모드(GOOSE_MODE)는 에이전트 쪽 모드로 옮겨집니다. Claude Code를 기준으로 보면 auto는 모든 권한 확인을 건너뛰고, smart-approve는 파일 수정만 자동으로 승인하고, approve는 모든 작업마다 확인하고, chat은 계획만 세우고 실행하지 않아요.

goose에 켜 둔 확장은 MCP 서버 형태로 Claude Code에 그대로 전달됩니다. goose에서 쓰던 도구를 Claude Code가 이어받는 셈이죠. 다만 ACP 제공자를 쓸 때는 세션 포크나 이어 하기를 아직 지원하지 않는다는 점은 알아 두세요.

참고로 Cursor Agent는 아직 CLI 제공자로 남아 있습니다. ACP의 동작 원리와 실제로 오가는 메시지는 ACP 글에서 자세히 다뤘어요.

MCP 확장

goose의 확장 시스템은 MCP 위에 구축되어 있습니다. 기본으로 제공되는 내장 확장부터 살펴볼까요?

developer: 파일 편집, 쉘 명령어 실행 등 기본 개발 도구 (기본으로 켜져 있음)
computercontroller: 앱과 시스템 설정 제어, PDF나 Word, Excel 문서 처리 등 컴퓨터 제어 기능
memory: 선호도나 자주 쓰는 정보를 세션 간에 기억하는 장기 메모리
autovisualiser: 데이터를 차트 같은 시각 자료로 자동 변환
tutorial: goose 사용법을 대화형으로 안내

이 밖에 goose 자체에 들어 있는 플랫폼 확장(platform extension)도 있습니다. 코드 구조를 분석하는 Analyze, 확장을 찾아 켜 주는 Extension Manager, 에이전트 스킬을 불러오는 Skills, 하위 작업을 다른 에이전트에게 맡기는 Summon이 기본으로 켜져 있어요. 작업 목록을 관리하는 Todo나 지난 대화를 검색하는 Chat Recall 같은 확장은 필요할 때 켜서 쓰면 됩니다.

외부 MCP 서버를 추가하려면 goose configure에서 “Add Extension”을 선택하면 됩니다.

goose configure

또는 세션을 시작할 때 직접 확장을 지정할 수도 있습니다.

# 내장 확장 추가
goose session --with-builtin memory

# 외부 MCP 서버 추가
goose session --with-extension 'npx -y @modelcontextprotocol/server-github'

# 원격 MCP 서버 추가
goose session --with-streamable-http-extension 'https://mcp.example.com/mcp'

MCP 생태계가 계속 커지고 있어서 GitHub, Slack, Google Drive, 데이터베이스 등 거의 모든 서비스와 연결할 수 있습니다. MCP를 더 자세히 알고 싶으시다면 Claude Code와 MCP를 참고해보세요.

레시피

레시피(Recipe)는 goose만의 특별한 기능입니다. 반복적인 작업 흐름을 YAML 파일로 정의해서 재사용하고 공유할 수 있죠.

간단한 코드 리뷰 레시피를 만들어볼까요?

code-review.yaml

version: 1.0.0
title: 코드 리뷰 도우미
description: Git diff를 분석해서 코드 리뷰를 수행합니다
instructions: |
  현재 브랜치의 변경사항을 main 브랜치와 비교해서 분석합니다.
  보안 취약점, 성능 이슈, 코드 스타일 문제를 찾아주세요.
  각 이슈에 대해 구체적인 개선 방안을 제시합니다.
prompt: "git diff main...HEAD 를 실행해서 변경사항을 분석해줘"
extensions:
  - type: builtin
    name: developer

extensions에는 확장 이름만 적지 않고 type과 name을 가진 객체로 적어야 합니다. - developer처럼 문자열로만 적으면 최신 goose에서는 invalid type: string "developer" 오류가 나요. 레시피를 작성한 뒤에는 goose recipe validate로 형식을 먼저 검사해 두면 좋습니다.

goose recipe validate code-review.yaml

결과

✓ recipe file is valid

이 레시피를 실행하려면 이렇게 하면 됩니다.

goose run --recipe code-review.yaml

레시피는 파라미터도 지원합니다. {{ variable_name }} 문법으로 동적인 값을 주입할 수 있죠.

deploy-check.yaml

version: 1.0.0
title: 배포 전 점검
description: 배포 전에 필요한 검사를 수행합니다
instructions: |
  {{ branch }} 브랜치의 코드를 점검합니다.
  테스트 실행, 린트 검사, 빌드 확인을 순서대로 수행하세요.
prompt: "{{ branch }} 브랜치에서 배포 전 점검을 시작해줘"
parameters:
  - key: branch
    input_type: string
    requirement: required
    description: 점검할 브랜치 이름
extensions:
  - type: builtin
    name: developer

파라미터 값은 --params로 넘깁니다. 어떤 파라미터가 필요한지 모르겠다면 --explain을 붙여서 먼저 확인해 보세요.

goose run --recipe deploy-check.yaml --params branch=main

레시피에는 자동 재시도 기능도 있습니다. 검증 명령어를 지정하면 성공할 때까지 자동으로 다시 시도해줍니다.

fix-tests.yaml

version: 1.0.0
title: 테스트 수정
description: 실패하는 테스트를 자동으로 수정합니다
instructions: |
  실패하는 테스트를 분석하고 코드를 수정해서 통과시켜주세요.
prompt: "테스트를 실행하고 실패하는 것을 수정해줘"
retry:
  max_retries: 3
  checks:
    - type: shell
      command: "bun test"
extensions:
  - type: builtin
    name: developer

진행 중인 세션에서 /recipe 명령어를 입력하면 현재 대화를 바탕으로 레시피를 자동 생성할 수도 있습니다. 자주 하는 작업이 있다면 레시피로 만들어두면 시간을 많이 아낄 수 있겠죠?

프로젝트 설정 파일

goose에게 프로젝트의 맥락을 알려주려면 AGENTS.md나 .goosehints 파일을 사용합니다. goose는 기본적으로 프로젝트에서 AGENTS.md를 먼저 찾고, 그다음 .goosehints를 찾아 세션을 시작할 때 자동으로 읽어 갑니다. OpenCode나 Codex처럼 AGENTS.md를 읽는 다른 에이전트와 파일 하나를 함께 쓸 수 있으니, 새로 만든다면 AGENTS.md로 시작하는 걸 추천해요.

AGENTS.md

이 프로젝트는 React + TypeScript 기반의 웹 앱입니다.

## 개발 서버

- `bun run dev`로 개발 서버를 실행합니다
- 포트 3000에서 동작합니다

## 테스트

- `bun run test`로 테스트를 실행합니다
- 테스트 파일은 `__tests__` 디렉토리에 있습니다

## 코드 스타일

- Prettier와 ESLint를 사용합니다
- 커밋 전에 `bun run lint`를 실행해주세요

Claude Code의 CLAUDE.md까지 함께 읽히고 싶다면 CONTEXT_FILE_NAMES 설정에 파일 이름을 추가하면 됩니다. 모든 프로젝트에 공통으로 적용할 지침은 ~/.config/goose/.goosehints에 적어 두세요.

이 파일을 Git에 커밋해두면 팀원들도 같은 맥락을 공유할 수 있습니다.

스케줄링

goose는 레시피를 정해진 시간에 자동으로 실행하는 스케줄링 기능도 제공합니다. 매일 아침 일일 리포트를 생성하거나, 주기적으로 코드 품질을 점검하는 식으로 활용할 수 있죠.

# 매일 오전 9시에 일일 리포트 생성
goose schedule add \
  --schedule-id daily-report \
  --cron "0 9 * * *" \
  --recipe-source ./recipes/daily-report.yaml

--cron에는 일반적인 5자리 cron 표현식이나 @hourly 같은 축약형을 쓰면 되고, 레시피에 파라미터가 있다면 --params로 함께 넘길 수 있습니다. 개발팀의 루틴 작업을 자동화하는 데 정말 유용한 기능입니다.

데스크톱 앱에서 파일 다루기

goose 데스크톱 앱은 채팅 중심의 앱이라 에디터처럼 디렉터리 트리를 보여 주거나 파일을 열어 보는 화면이 없습니다. CLI도 마찬가지로 대화형 세션만 제공하고요. 파일을 읽고 고치는 일은 사람이 아니라 developer 확장을 쓰는 에이전트가 맡는 구조입니다.

대신 파일과 관련된 기능이 몇 가지 있습니다. 우선 입력창에 @를 입력하면 작업 디렉터리의 파일과 폴더 목록이 뜨고, 고른 경로가 메시지에 들어갑니다. 에이전트에게 “이 파일을 봐 달라”고 가리키는 자동 완성인 셈이죠. 그리고 하단 메뉴의 디렉터리 전환기나 “Open Directory” 단축키로 작업 폴더를 바꿀 수 있고, 같은 메뉴에서 현재 작업 폴더를 Finder나 파일 탐색기로 열 수 있어요.

파일 내용을 확인하고 싶다면 “src/main.ts 내용을 보여 줘”처럼 goose에게 요청하면 됩니다. 파일 트리를 보면서 작업하는 게 편하다면 OpenCode의 데스크톱 앱처럼 파일 브라우저를 갖춘 도구를 쓰거나, 다음에 소개할 방법으로 goose를 에디터 안에 붙이는 편이 낫습니다.

에디터 연동

터미널이나 데스크톱 앱에서만 쓸 수 있는 건 아닙니다. goose는 goose acp 명령으로 ACP 에이전트 서버가 될 수 있어서, ACP를 지원하는 에디터라면 어디든 붙일 수 있어요.

JetBrains IDE와 Zed는 ACP 에이전트 레지스트리에서 goose를 골라 바로 설치할 수 있습니다. 로컬에 설치한 goose를 쓰고 싶다면 Zed의 settings.json에 직접 등록하면 됩니다.

settings.json

{
  "agent_servers": {
    "goose": {
      "type": "custom",
      "command": "goose",
      "args": ["acp"]
    }
  }
}

VS Code용 확장도 있는데, 아직 실험 단계이고 내부적으로는 역시 ACP로 goose와 통신합니다. Zed의 AI 기능에서 소개한 에이전트 패널처럼, 에디터에서 쓰면 파일 트리와 diff 화면을 그대로 쓰면서 선택 영역이나 열린 파일을 컨텍스트로 넘기기 편해요. 데스크톱 앱에 없는 파일 화면을 에디터가 채워 주는 셈입니다.

Docker 컨테이너 활용

보안이 중요한 환경이라면 goose의 확장을 Docker 컨테이너 안에서 실행할 수 있습니다.

# 컨테이너 안에서 확장을 실행하며 세션 시작
goose session --container my-dev-container

# 컨테이너 안에서 확장을 실행하며 작업 수행
goose run --container my-dev-container --text "의존성을 업데이트해줘"

--container를 지정하면 stdio 확장과 내장 확장이 호스트가 아닌 컨테이너 안에서 돌아갑니다. 파일 편집이나 쉘 명령 같은 작업이 컨테이너에 갇히니 호스트 시스템을 건드릴 걱정이 줄어들어요. 다만 확장이 컨테이너 안에 설치되어 있어야 하고, developer 같은 내장 확장을 쓰려면 컨테이너 안에도 goose가 설치되어 있어야 합니다. Ollama와 함께 사용하면 데이터가 외부로 전혀 나가지 않는 완전한 로컬 환경을 구축할 수도 있죠.

Claude Code와 비교

같은 AI 코딩 에이전트인 Claude Code와 어떤 차이가 있는지 궁금하실 텐데요.

Claude Code는 Anthropic의 Claude 모델에 최적화되어 있어서, Claude의 성능을 최대한 끌어내는 데 집중합니다. 반면 goose는 어떤 모델이든 가져다 쓸 수 있는 유연성이 장점이죠. 팀에서 이미 특정 클라우드 제공자를 사용하고 있거나, 보안상 로컬 모델만 써야 하는 환경이라면 goose가 더 적합할 수 있습니다.

레시피와 스케줄링 기능도 goose만의 강점입니다. 반복 작업을 YAML로 정의하고 팀원들과 공유할 수 있다는 건 실무에서 꽤 매력적인 포인트입니다.

하지만 단일 모델의 성능을 극한까지 활용하는 면에서는 Claude Code가 앞섭니다. goose도 Summon 확장으로 하위 작업을 위임할 수 있게 됐지만, 서브 에이전트나 에이전트 팀 같은 고급 기능은 아직 Claude Code 쪽이 더 다듬어져 있어요. 그리고 이제는 둘 중 하나만 고를 필요도 없습니다. 앞에서 본 ACP 제공자를 쓰면 goose의 레시피와 스케줄링 위에서 Claude Code를 엔진으로 돌릴 수 있으니까요.

마치며

goose는 특정 LLM에 종속되지 않으면서도 강력한 에이전트 기능을 제공하는 독특한 도구입니다. MCP 기반의 확장 시스템, 재사용 가능한 레시피, 스케줄링 같은 기능은 개인 개발자뿐만 아니라 팀 단위 자동화에도 활용할 수 있어 보입니다. Agentic AI Foundation으로 옮겨 간 뒤로는 ACP 제공자나 goose review 같은 기능이 빠르게 추가되고 있어서, 예전에 써 봤다면 최신 버전으로 다시 한번 살펴볼 만해요.

Apache 2.0 라이선스의 오픈소스이니 부담 없이 한번 설치해서 써보세요. 특히 이미 다른 AI 코딩 도구를 사용하고 계신 분이라면, goose의 접근 방식이 어떻게 다른지 비교해보는 것도 재미있을 겁니다.

더 자세한 내용은 goose 공식 문서와 GitHub 저장소를 참고하세요.

This work is licensed under CC BY 4.0

goose가 다른 점

설치

초기 설정

세션 시작하기

비대화형 실행

ACP 제공자로 Claude Code와 Codex 구독 쓰기

MCP 확장

레시피

프로젝트 설정 파일

스케줄링

데스크톱 앱에서 파일 다루기

에디터 연동

Docker 컨테이너 활용

Claude Code와 비교

마치며

개발자를 위한 뉴스레터

관련 포스트

클로드 코드: 터미널 기반 코딩 에이전트

OpenCode: 오픈소스 AI 코딩 에이전트와 Desktop v2

ACP: 에디터와 코딩 에이전트를 잇는 표준 프로토콜

클로드 코드에서 MCP 서버 연동하기

AI를 위한 프로젝트 안내서: AGENTS.md와 CLAUDE.md

Codex CLI: OpenAI가 만든 터미널 코딩 에이전트