Ferret 사용하기

에이전트로 보내기

코딩 에이전트를 내장 터미널에서 실행하고, 클릭 한 번으로 리뷰를 넘깁니다. Claude Code와 Codex가 대표적인 예이지만, 아래 목록에 있는 에이전트라면 무엇이든 사용할 수 있고 직접 추가한 CLI도 사용할 수 있습니다. 다른 곳에서 실행 중인 에이전트를 위해 지시를 복사하거나, 리뷰를 GitHub에 게시할 수도 있습니다.

#지적 사항 검토

지적 사항 탭의 각 카드에서는 다음을 할 수 있습니다.

제목과 요청을 그 자리에서 편집
보내기 / 보내지 않음 전환
녹화 보기(해당 시점으로 이동)와 이미지 교체(다른 프레임 선택)
확인 완료 / 확인 필요로 표시, 다음과 병합, 삭제

진행 상태로 필터는 상태별로 지적 사항을 표시하거나 숨깁니다(예: 내 검토를 기다리는 것만 표시). 모두 표시를 누르면 필터가 해제됩니다.

헤더에는 실행 취소, 폴더 열기, 에이전트용으로 복사, GitHub / GitLab로 보내기, 정리, 에이전트에게 보내기가 있습니다. 지적 사항이 되지 않은 발화는 제외된 발화에 나열되며, 지적 사항으로 복원으로 되돌릴 수 있습니다.

스크린샷 준비 중

지적 사항 탭

#내장 터미널에서 에이전트 실행

프로젝트를 열면 Ferret은 설정 → 에이전트 → 프로젝트를 열 때 시작에 있는 에이전트마다 터미널 탭을 하나씩, 프로젝트 폴더에서 에이전트의 일반 모드로 시작합니다. 기본값은 Claude Code와 Codex입니다.

claude
codex

대신 지원 목록에서 원하는 에이전트를 고를 수 있으며(고른 순서대로 시작됩니다), 아무것도 고르지 않아도 됩니다.

권한 확인은 켜진 상태로 유지됩니다

프로젝트를 등록하거나 클론해도 Ferret이 그 프로젝트를 신뢰하게 되지는 않습니다. Claude Code나 Codex 같은 에이전트는 처음에 폴더를 신뢰할지 묻고, 이후에도 파일을 편집하거나 명령을 실행하기 전에 계속 확인합니다. 신뢰하는 프로젝트 하나에서 에이전트가 권한 확인, 승인, 샌드박스를 건너뛰게 하려면 설정 → 에이전트 → 권한 확인 건너뛰기에서 그 프로젝트에 대해 켜고 확인하세요. Ferret은 알려진 경우 각 에이전트 고유의 건너뛰기 플래그를 추가하며, 알려진 플래그가 없는 에이전트는 확인을 유지합니다. 이 설정은 그 프로젝트 폴더에서 직접 연 에이전트에만 적용되며, 프로젝트를 열 때 시작되는 에이전트는 항상 확인을 유지합니다. 인수에 직접 입력한 권한 건너뛰기 플래그는 무시됩니다.

선택된 에이전트가 없으면 일반 셸이 열립니다. + 메뉴에서는 새 터미널을 열거나, 에이전트를 새 탭에서 실행하거나, 에이전트 설정…으로 이동할 수 있습니다. 이 메뉴의 검색 상자로 탭, 저장된 URL, 파일도 찾을 수 있습니다.

탭에는 에이전트 상태가 표시됩니다: 실행 중, 입력 대기 중, 완료(읽지 않음), 대기. 사이드바에서는 에이전트가 실행 중인 프로젝트에 표시가 붙으므로 프로젝트를 전환하지 않아도 알 수 있습니다.

터미널 탭과 창을 드래그해 분할하고, 옮기고, 다시 탭으로 되돌리는 모습.

드래그로 분할. 탭을 드래그하거나, 창을 핸들(탭이 분할되면 표시됨)로 드래그해서 다음 위치에 놓습니다.

창 가장자리의 바깥쪽 4분의 1: 왼쪽으로 분할 / 오른쪽으로 분할 / 위로 분할 / 아래로 분할
창의 가운데: 탭으로 열기(창이 분할에서 빠져 독립된 탭이 됩니다)
터미널 영역 전체를 둘러싼 얇은 띠: 전체 영역을 왼쪽으로 분할 등(창이 2개 이상일 때)
탭 표시줄: 여기에 탭으로 배치

옮기는 동안에도 프로세스는 계속 실행되며, 비어 있게 된 탭은 닫힙니다. 키보드로 분할하기:

동작	macOS	Windows / Linux
새 터미널	`⌘T`	`CtrlT`
오른쪽으로 분할	`⌘D`	`CtrlShiftD`
아래로 분할	`⌘⇧D`	`AltShiftD`
창 / 탭 닫기	`⌘W`	`CtrlW`

#지원하는 에이전트

Ferret은 특정 에이전트에 묶여 있지 않습니다. 아래의 코딩 에이전트를 인식하여, 시작하고, 에이전트에게 보내기를 위해 터미널에서 감지하고, 설치 여부를 표시할 수 있습니다. 설정 → 에이전트에는 각 에이전트가 설치됨 / 찾을 수 없음 상태와 함께 나열되며, 제공사가 한 줄 설치 프로그램을 공개한 경우 설치 버튼, 그리고 각각의 명령과 인수가 표시됩니다.

Claude Code (새 탭에서 열림) claude
Codex (새 탭에서 열림) codex
Gemini CLI (새 탭에서 열림) gemini
Cursor (새 탭에서 열림) agent
GitHub Copilot (새 탭에서 열림) copilot
Devin (새 탭에서 열림) devin
OpenCode (새 탭에서 열림) opencode
Amp (새 탭에서 열림) amp
Droid (새 탭에서 열림) droid
Kiro (새 탭에서 열림) kiro-cli chat
Aider (새 탭에서 열림) aider
Ante (새 탭에서 열림) ante
Antigravity (새 탭에서 열림) agy
Auggie (새 탭에서 열림) auggie
Autohand Code (새 탭에서 열림) autohand
BLACKBOX CLI (새 탭에서 열림) blackbox
Cline (새 탭에서 열림) cline
CodeBuddy (새 탭에서 열림) codebuddy
Codebuff (새 탭에서 열림) codebuff
Command Code (새 탭에서 열림) command-code --trust
Continue (새 탭에서 열림) cn
Charm (Crush) (새 탭에서 열림) crush
DeepSeek Harness (새 탭에서 열림) dsh tui
ForgeCode (새 탭에서 열림) forge
Freebuff (새 탭에서 열림) freebuff
Goose (새 탭에서 열림) goose session
Grok (새 탭에서 열림) grok
Hermes Agent (새 탭에서 열림) hermes --tui
Junie CLI (새 탭에서 열림) junie
Kilocode (새 탭에서 열림) kilo
Kimi (새 탭에서 열림) kimi
Letta Code (새 탭에서 열림) letta
MiMo Code (새 탭에서 열림) mimo
Mistral Vibe (새 탭에서 열림) vibe
Muse (새 탭에서 열림) muse --trust-workspace
oh-my-pi (새 탭에서 열림) omp
OpenClaude (새 탭에서 열림) openclaude
OpenClaw (새 탭에서 열림) openclaw chat
OpenHands CLI (새 탭에서 열림) openhands
Pi (새 탭에서 열림) pi
Prime Agent (새 탭에서 열림) prime-agent
Qoder CLI (새 탭에서 열림) qoder
Qwen Code (새 탭에서 열림) qwen
Roo Code CLI (새 탭에서 열림) roo
Rovo Dev (새 탭에서 열림) acli rovodev run
Trae CLI (새 탭에서 열림) traecli
ZCode (새 탭에서 열림) zcode

목록에 없나요? 설정 → 에이전트 → 사용자 지정 에이전트 추가로 어떤 CLI나 래퍼 스크립트든 등록할 수 있습니다(이름, 명령, 그리고 선택적으로 인식에 쓰는 프로세스 이름). 또는 settings.json의 agents.customAgents에 추가하세요. Ferret 밖에서 실행 중인 에이전트에는 에이전트용으로 복사를 사용할 수 있습니다.

일부 기능은 에이전트에 따라 달라지며, 현재는 Claude Code와 Codex로 한정됩니다.

계정과 사용량: 여러 로그인 간 전환과 푸터의 사용량 한도 미터.
정리: Claude Code 또는 Codex 로그인, 혹은 직접 설정한 LLM API로 실행됩니다.

#에이전트에게 보내기 / 에이전트용으로 복사

지적 사항 탭에서 에이전트에게 보내기로 내장 터미널의 에이전트에 전달하는 모습.

에이전트에게 보내기를 클릭합니다. 기본값(자동(현재 탭 또는 실행 중인 에이전트))에서는 현재 터미널 탭의 에이전트나 실행 중인 에이전트로 보냅니다. 버튼 옆의 화살표(보낼 에이전트 선택)로 특정 에이전트나 탭을 고를 수 있습니다.
Ferret이 에이전트의 입력란에 지시를 써 넣고 제출합니다. 진행 상황은 터미널에서 확인하세요.

실행 중인 에이전트가 없으면 Ferret이 먼저 하나를 시작하고, 준비되는 대로 보냅니다. 에이전트가 권한 확인에 대한 응답을 기다리는 동안에는 아무것도 보내지 않습니다. 먼저 터미널에서 응답하세요.

에이전트용으로 복사는 다른 곳(다른 터미널, IDE, 앱)에서 실행 중인 에이전트를 위해 같은 지시를 클립보드에 넣습니다. 보내기로 설정된 지적 사항만 대상이 됩니다. 동영상은 절대 포함되지 않습니다.

#판정 모델로 완료 검사

에이전트가 지적 사항을 고치고, 모두 통과할 때까지 판정 모델로 하나씩 확인하는 모습.

이 기능을 켜면 코딩 에이전트가 완료를 보고하기 전에 지적 사항마다 자신의 작업을 스스로 확인합니다. Ferret 자체는 아무것도 판정하지 않습니다. 에이전트에게 판정 모델(System One 호환 API라면 무엇이든)을 제공하고, feedback.md에서 모든 지적 사항이 통과할 때까지 반복하라고 지시합니다.

에이전트가 지적 사항을 구현합니다.
지적 사항마다 AFTER 스크린샷(BEFORE 정지 화면과 같은 뷰포트, 같은 페이지 상태)을 찍고, 지적 사항의 텍스트, "완료 조건" 줄, BEFORE/AFTER 이미지를 담은 요청 하나를 판정 모델에 보냅니다.
P(done)이 임계값(기본값 0.7) 이상이고 choice가 done이면 그 지적 사항은 통과입니다. 에이전트는 나머지를 고치고 매 라운드마다 모든 지적 사항을 다시 판정하며, 같은 라운드에서 모든 지적 사항이 통과했을 때, 또는 반드시 밝혀야 하는 정당한 이유가 있을 때만 멈춥니다: API에 연결할 수 없음, 지적 사항이 범위를 벗어남, 점수가 변하지 않은 채 지적 사항이 막혀 있음.
최종 완료 / 미완료 목록에는 각 지적 사항의 점수와 라운드 수가 포함됩니다.

설정 → 판정 모델에서 설정하고 에이전트 지시에 판정 모델 검사 추가를 켜세요. 프리셋은 필드를 채울 뿐이며 모든 필드는 계속 편집할 수 있고, 사용자 지정은 호환되는 어떤 API와도 동작합니다.

프리셋	요청 URL	모델	키
Ollama(기본값)	`http://localhost:11434/v1/systemone`	`clef-flash`, `clef`(이미지 읽기 가능); `nimble`, `tev1`(텍스트 전용)	없음, 무료
Cloudflare Workers AI	`https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}`	`clef-flash`, `clef`(이미지 읽기 가능)	`CLOUDFLARE_API_TOKEN`(Workers AI 권한); 계정 ID는 필드 또는 `CLOUDFLARE_ACCOUNT_ID`에서
Vercel AI Gateway	`https://ai-gateway.vercel.sh/typesafe/v1/systemone`	`typesafe-ai/jev`, `convaiinnovations/laya`(텍스트 전용)	`AI_GATEWAY_API_KEY`
TypeSafe	`https://api.typesafe.ai/v1/systemone`	`jev-latest`, `jev-preview`(텍스트 전용)	`TYPESAFE_API_KEY`
사용자 지정	임의의 전체 URL	임의	Bearer, 사용자 지정 헤더, 또는 없음; 추가 헤더 사용 가능

Ollama를 쓰려면 설치하고(Clef / Clef Flash에는 0.35.1 이상) 터미널에서 모델을 내려받으세요. Ferret은 설치 프로그램을 실행하지 않습니다.

ollama pull clef-flash

키는 키 필드(다른 API 키와 함께 저장됨), 지정한 이름의 환경 변수(앱의 환경, 프로젝트의 .env, 또는 ~/.ferret/.env), 또는 settings.json의 apiKey에서 가져옵니다. 추가 헤더는 ${VAR}로 환경 변수의 값을 읽을 수 있습니다.

키가 프롬프트에 들어가지 않는 방식

에이전트는 키를 절대 보지 못합니다. Ferret은 127.0.0.1에서 로컬 릴레이를 실행하고, 각 터미널에 FERRET_DECISION_URL(터미널별 토큰이 붙은 릴레이), FERRET_DECISION_MODEL, FERRET_DECISION_IMAGES를 전달합니다(한 릴리스 동안은 예전 이름인 MOVIE_ADE_DECISION_*도 함께 설정됩니다). 릴레이는 키와 헤더를 붙여 요청을 그대로 전달하므로 프롬프트, feedback.md, 에이전트의 대화 기록에는 비밀 정보가 남지 않습니다. 설정을 바꾼 뒤에 연 터미널부터 새 값이 적용됩니다.

Cloudflare는 System One 문서와 두 가지 점에서 다릅니다(실제 API로 확인함). 이미지는 data URI(data:image/jpeg;base64,…)여야 하며, 그렇지 않으면 422 "image must be an embedded base64 data URI"가 반환됩니다. 또한 응답이 { "result": { … }, "success": true }로 감싸여 옵니다(오류는 { "success": false, "errors": [ … ] }로 옵니다). Cloudflare 프리셋은 이미지 인코딩을 data URI로 설정하고, 에이전트는 이를 FERRET_DECISION_IMAGE_FORMAT으로 받으며, 지시에는 .result가 있으면 그것을 읽으라고 적혀 있습니다. 릴레이는 양방향 모두 그대로 전달합니다. API 토큰 대신 Global API Key를 쓰려면 인증을 키 없음으로 설정하고 X-Auth-Email: ${CLOUDFLARE_EMAIL}과 X-Auth-Key: ${CLOUDFLARE_API_KEY} 헤더를 추가하세요.

이미지를 읽을 수 있는 것은 Clef와 Clef Flash뿐입니다. 텍스트 전용 모델을 쓸 때는 BEFORE/AFTER 이미지 전송을 끄세요. 그러면 에이전트는 텍스트만으로 판정하므로 신뢰도가 떨어집니다.

Ollama와 큰 이미지

Ollama 0.35.0은 /v1/systemone 요청을 64 KiB로 제한하므로, 스크린샷이 포함된 요청은 HTTP 413으로 실패합니다. 지시에는 두 이미지를 너비 최대 1024px의 JPEG(품질 약 70)로 줄이라고 적혀 있습니다. 그래도 413이 나오면 Ollama를 0.35.1 이상으로 업데이트하거나 Cloudflare Workers AI로 바꾸세요.

#푸터의 API 사용량

판정 호출은 릴레이를 거치므로 Ferret이 횟수를 셀 수 있습니다. 푸터에서 에이전트 사용량 미터 옆 항목에 판정 모델과 오늘의 호출 수, 토큰, 비용이 표시됩니다(예: clef-flash · 42 calls · 18.3k tok). 클릭하면 오늘, 이번 달, 프로젝트별, 모델별, 종류별(판정 / 음성 인식 / 정리) 집계와 최근 50건의 호출을 볼 수 있습니다.

비용은 API가 보고하는 경우(Vercel AI Gateway는 보고합니다)나 설정 → 판정 모델에서 100만 토큰당 가격을 설정한 경우에만 표시되며, 그 외에는 "—"로 표시됩니다. 기록되는 것은 메타데이터(시각, 프로젝트, 모델, 상태, 지연 시간, 크기, 이미지 수, 토큰, 비용)뿐이며 이미지, 텍스트, 키는 절대 기록되지 않습니다. 기록은 ~/.ferret/usage/decision-YYYY-MM.jsonl에 한 달에 한 파일씩 저장됩니다.

#지시 바꾸기

설정 → 에이전트 → 에이전트에게 보낼 지시를 편집하세요. 변수 두 개가 치환됩니다.

변수	치환 결과
`{{path}}`	`feedback.md`의 절대 경로
`{{relpath}}`	프로젝트 기준 상대 경로: `.ferret/reviews/<id>/feedback.md`

비워 두면 기본값을 사용합니다. 최대 길이는 2000자이며, 지시 초기화로 기본값을 복원할 수 있습니다. 예:

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

이 설정은 settings.json에 agentPrompt로 저장됩니다.

#GitHub 또는 GitLab으로 보내기(Issue / PR 또는 MR 코멘트)

GitHub로 보내기는 리뷰를 새 Issue로, 또는 내가 연 풀 리퀘스트 중 하나에 코멘트로 게시합니다. 인증은 GitHub CLI (새 탭에서 열림)에 맡깁니다. Ferret은 토큰을 읽거나 저장하지 않습니다.

gh를 설치합니다: brew install gh(macOS), winget install --id GitHub.cli(Windows), 또는 cli/cli (새 탭에서 열림)를 참고하세요.
설정 → GitHub / GitLab → 터미널에서 로그인은 내장 터미널에서 gh auth login --web -h github.com을 실행합니다.
GitHub로 보내기를 클릭하고 새 Issue 만들기 또는 PR을 선택한 뒤, 제목과 본문(편집 가능)을 확인합니다.
확인 체크박스를 선택한 뒤 Issue 만들기 또는 코멘트 게시를 누릅니다.

세부 사항:

저장소는 git remote get-url origin에서 가져옵니다.
Ferret은 gh issue create --repo … --title … --body-file - 또는 gh pr comment <n> --repo … --body-file -을 실행합니다.
본문은 이미지 줄을 뺀 feedback.md이며(이미지는 업로드하지 않음), 최대 60,000자입니다.
PR 후보는 내가 연 열린 PR(최대 30개)입니다.

GH_TOKEN 또는 GITHUB_TOKEN이 설정되어 있으면 gh가 그것을 먼저 사용하며, 설정 패널에 경고가 표시됩니다.

GitLab. origin이 GitLab 프로젝트(gitlab.com 또는 자체 관리형 GitLab)이면 같은 버튼이 GitLab CLI (새 탭에서 열림)(glab)를 통해 GitLab으로 보냅니다: 새 Issue, 또는 내가 연 열린 머지 리퀘스트 중 하나에 코멘트. 로그인은 설정 → GitHub / GitLab에서 하며, 내장 터미널에서 glab auth login(자체 관리형 GitLab이면 --hostname 포함)을 실행합니다. Ferret은 토큰을 읽거나 저장하지 않으며, GITLAB_TOKEN이 설정되어 있으면 경고합니다.

스타 요청. 처음 에이전트에게 보내기를 한 뒤, 그리고 완료한 리뷰가 3, 10, 30개가 되었을 때 Ferret이 GitHub에서 스타를 달라고 요청할 수 있습니다. 요청은 최대 3번, 최소 3일 간격으로 하며, 녹화 중에는 절대 하지 않습니다. GitHub에서 스타는 내 gh 로그인으로 스타를 주고(gh를 쓸 수 없으면 GitHub를 엽니다), 다시 묻지 않기를 누르면 요청이 멈춥니다. 도움말 → GitHub에서 Ferret에 스타 주기에서도 스타를 줄 수 있습니다.

#CLI 도구 설치와 로그인

설정 → CLI 도구는 에이전트가 자주 필요로 하는 명령줄 도구를 나열하고, 설치 여부와 버전을 보여 주며, 내 OS용 공식 설치 명령이나 로그인 명령을 새 터미널 탭에서 실행합니다.

Git 호스팅: gh, glab
AI와 모델: Ollama, Cloudflare wrangler
배포: Vercel, Netlify, Fly.io, Railway, Heroku
클라우드와 서비스: Supabase, Firebase, Stripe, Google Cloud(gcloud), AWS, Azure, Docker

내 OS용 한 줄 공식 설치 프로그램이 없는 도구는 대신 문서가 설치 페이지를 엽니다. 설치가 끝나면 목록이 자동으로 다시 확인합니다.

GitHub에서 이 페이지 번역 돕기 (새 탭에서 열림)