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

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

바로 Block(구 Square)이 만든 오픈소스 AI 코딩 에이전트, Goose입니다.

Goose는 2025년 1월에 처음 공개된 이후 빠르게 성장해서, 지금은 GitHub 스타 27,000개 이상, 기여자 400명 이상의 대규모 오픈소스 프로젝트가 되었습니다. 2025년 12월에는 Linux Foundation의 Agentic AI Foundation에 합류하면서 AI 에이전트 생태계의 핵심 프로젝트로 자리매김했죠.

Goose가 다른 점

Goose의 가장 큰 특징은 특정 LLM에 종속되지 않는다는 점입니다. Claude Code는 당연히 Claude 모델만 사용하고, 대부분의 코딩 에이전트도 특정 모델에 최적화되어 있는데요. Goose는 25개 이상의 LLM 제공자를 지원합니다. Anthropic의 Claude, OpenAI의 GPT, Google의 Gemini 같은 클라우드 모델은 물론이고 Ollama를 통한 로컬 모델까지 자유롭게 선택할 수 있습니다.

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

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

설치

Goose는 macOS, Linux, Windows 모두에서 사용할 수 있습니다.

Linux와 macOS에서는 설치 스크립트 한 줄이면 됩니다.

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

Windows에서는 Git Bash나 PowerShell에서 같은 명령어를 실행하면 됩니다. 데스크톱 앱을 선호하신다면 GitHub 릴리즈 페이지에서 직접 다운로드할 수도 있습니다.

초기 설정

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

goose configure

이 명령어를 실행하면 설정 메뉴가 나타납니다.

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

“Configure Providers”를 선택하면 사용할 LLM 제공자를 고를 수 있습니다. Anthropic, OpenAI, Google, Amazon Bedrock, Azure OpenAI 같은 클라우드 서비스부터 Ollama 같은 로컬 제공자까지 선택지가 넓습니다.

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

GOOSE_PROVIDER: anthropic
GOOSE_MODEL: claude-sonnet-4-20250514
extensions:
  developer:
    enabled: true
    name: developer
    type: builtin
  computercontroller:
    enabled: true
    name: computercontroller
    type: builtin

세션 시작하기

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

goose session

이 명령어를 실행하면 대화형 세션이 시작되고, Goose가 현재 디렉토리를 작업 컨텍스트로 인식합니다. 이제 자연어로 원하는 작업을 요청하면 됩니다.

( O_O) > 이 프로젝트의 구조를 분석하고 README를 작성해줘

I'll analyze the project structure first...

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

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

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

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

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

비대화형 실행

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

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

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

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

CI/CD 파이프라인에서 활용하거나, 쉘 스크립트의 일부로 Goose를 끼워넣을 때 유용합니다. --no-session 옵션을 추가하면 세션 파일도 생성하지 않아서 깔끔하죠.

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

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

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

MCP 확장

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

• developer — 파일 읽기/쓰기, 쉘 명령어 실행, 코드 검색 등 기본 개발 도구
• computercontroller — 브라우저 자동화, 스크린샷 캡처 등 컴퓨터 제어 기능
• memory — 세션 간 정보를 기억하는 장기 메모리

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

goose configure

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

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

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

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

레시피

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

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

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

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

goose run --recipe code-review.yaml

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

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

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

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

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

프로젝트 설정 파일

Goose에게 프로젝트의 맥락을 알려주려면 .goosehints 파일을 사용합니다. Claude Code의 CLAUDE.md나 OpenCode의 AGENTS.md와 비슷한 역할을 하는데요, 프로젝트 루트에 이 파일을 만들어두면 Goose가 세션을 시작할 때 자동으로 읽어갑니다.

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

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

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

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

이 파일을 Git에 커밋해두면 팀원들도 같은 맥락을 공유할 수 있습니다. 프로젝트 컨텍스트 파일에 대해 더 알고 싶으시다면 AGENTS.md와 CLAUDE.md에서 자세히 다루고 있습니다.

스케줄링

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

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

개발팀의 루틴 작업을 자동화하는 데 정말 유용한 기능입니다.

IDE 연동

터미널에서만 쓸 수 있는 건 아닙니다. VS Code, Cursor, Windsurf, JetBrains IDE에서도 확장 프로그램으로 쓸 수 있죠.

IDE에서 사용하면 에디터의 파일 컨텍스트를 자동으로 공유받기 때문에 더 정확한 답변을 얻을 수 있습니다. 다만 터미널 CLI가 가장 유연하고 기능이 풍부하기 때문에 복잡한 작업은 CLI를 추천합니다.

Docker 컨테이너 활용

보안이 중요한 환경이라면 Goose를 Docker 컨테이너 안에서 실행할 수도 있습니다.

# 컨테이너 안에서 세션 시작
goose session --container my-dev-container

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

Goose가 수행하는 모든 명령어가 컨테이너 내부로 격리되기 때문에, 호스트 시스템에 영향을 주지 않아요. Ollama와 함께 사용하면 데이터가 외부로 전혀 나가지 않는 완전한 로컬 환경을 구축할 수도 있죠.

Claude Code와 비교

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

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

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

하지만 단일 모델의 성능을 극한까지 활용하는 면에서는 Claude Code가 앞서고, 에이전트 간 협업이나 서브 에이전트 같은 고급 기능도 Claude Code 쪽이 더 성숙합니다. 결국 어떤 도구가 더 좋다기보다는 팀의 상황과 요구사항에 맞는 도구를 선택하는 게 중요하겠죠.

마치며

Goose는 특정 LLM에 종속되지 않으면서도 강력한 에이전트 기능을 제공하는 독특한 도구입니다. MCP 기반의 확장 시스템, 재사용 가능한 레시피, 스케줄링 같은 기능은 개인 개발자뿐만 아니라 팀 단위 자동화에도 활용할 수 있어 보입니다.

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

Goose에 대한 더 자세한 정보는 공식 문서와 GitHub 저장소에서 확인할 수 있습니다.