사용 설명서

snowpea 사용 설명서는 터미널 UI(TUI)와 데스크톱 앱의 주요 화면에서 보이는 정보와 수행할 작업을 다룹니다.

이 문서에서 다루는 내용

• 터미널에서 사용하기
• 데스크톱 앱에서 사용하기
• 다음 문서 고르기

터미널에서 사용하기

터미널 UI(TUI)는 snowpea 를 인자 없이 실행하면 열리는 클라이언트입니다. 툴 실행 권한, 명령 해석, 컨텍스트 압축은 데몬(snowpea core)이 결정합니다.

1.1 설정 마법사

The first-run setup wizard on the vendor screen: the eleven vendors, the star on the default, and the auth choices.

설정 마법사는 첫 실행 또는 snowpea setup --full 로 여는 프로바이더 설정 화면입니다. Providers 화면에는 코어에 들어 있는 열한 개 벤더가 표시되고 기본값에는 별표가 붙습니다. 오른쪽에는 각 벤더가 지원하는 인증 방식이 표시됩니다.

항목	값
다시 열기	snowpea setup --full
프로바이더 수	열한 개
인증 방식	API 키, 브라우저 로그인(디바이스 코드 또는 OAuth PKCE)
기본값 표시	별표

1. 커서를 이미 계정이 있는 벤더로 이동하고 Enter 를 누릅니다.
2. 다음 화면에서 인증 방식을 선택합니다.
3. API 키를 붙여 넣거나 브라우저 로그인을 시작합니다.
4. 환경변수에 키가 있으면 해당 키 사용 여부를 선택합니다.
5. 기본값을 유지하려면 Skip — keep defaults 를 선택합니다.

나중에 snowpea setup providers 로 모델 프로필을 여러 개 등록하고 에이전트별로 배정할 수 있습니다.

1.2 실행 화면

The TUI launch screen: banner, version line, the working directory, the active vendor and model, and the mode indicator.

실행 화면은 세션이 시작될 때 한 번 표시되는 화면입니다. 터미널 폭에 맞춰 크기가 정해지는 워드마크 아래에 태그라인과 버전 · 벤더/모델 · 작업 디렉터리 · 모드 가 표시됩니다.

데몬에 현재 디렉터리의 세션이 있으면 마지막 세션 시각, 마지막 프롬프트, R 또는 /resume 안내가 표시됩니다. 해당 세션이 없으면 이 블록은 표시되지 않습니다.

1. 마지막 세션을 이어서 열려면 빈 입력에서 R 을 누릅니다.
2. 저장된 세션 전체에서 선택하려면 /resume 또는 /sessions 를 입력합니다.
3. 새 세션을 시작하려면 프롬프트를 입력합니다.

배너는 한 번만 표시됩니다.

1.3 진행 중인 세션

A live session mid-answer: user prompt, streaming assistant text, a tool call with its arguments collapsed, and the status bar showing tokens and elapsed time.

진행 중인 세션 화면은 출력 기록과 입력 영역으로 구성됩니다. 위쪽에는 프롬프트, 접힌 툴 호출, 스트리밍된 답변이 표시됩니다. 터미널 UI는 전체 화면 애플리케이션이 아니라 인라인으로 그려지므로 위로 흘러간 출력은 터미널 스크롤백에 남고 마우스와 Ctrl+Shift+F 를 사용할 수 있습니다.

살아 있는 영역은 작업 표시 줄, 입력, 모드 요약 줄, 상태 줄, 컨텍스트 경고, 에이전트 행 순서입니다. 컨텍스트 경고는 조건이 있을 때만 표시됩니다.

상태 줄 형식은 다음과 같습니다.

snowpea v0.1.2 | ~/project | Model: anthropic/claude-sonnet-4-5 | Mode: ACCEPT | ctx 34% (68k/200k)

표시	의미
ctx	모델 컨텍스트 창 사용량
70% 미만	흐리게 표시
70% 이상	호박색 표시
85% 이상	빨간색 표시
80% 초과	[!!] context 85% — /compact to free space 경고 표시

1. 턴이 실행되는 동안 다음 프롬프트를 입력합니다.
2. 입력한 프롬프트는 큐에 들어가고 선입선출로 처리됩니다.
3. 현재 턴과 큐를 버리려면 Esc 를 누릅니다.
4. 가장 최근 툴 호출이나 diff를 펼치려면 Ctrl+O 를 누릅니다.
5. 히스토리 끝에서 ↓ 를 눌러 입력 아래 패널로 이동합니다.
6. 에이전트 행에서 Enter 를 눌러 해당 에이전트의 대화를 엽니다.

1.4 승인

An approval prompt in accept mode: the tool, the exact command, the permission tag, and the allow / allow-always / deny choices.

승인 메뉴는 accept 모드에서 셸 명령이나 네트워크 호출처럼 승인이 필요한 툴이 요청될 때 표시됩니다. 위쪽에는 툴 이름, 위험도, 타임아웃이 표시되고 아래에는 실행될 명령이 표시됩니다. 데몬 경고가 있으면 인자 위에 빨간 ⚠ 줄이 표시됩니다.

선택	키	범위
Yes	y	이 호출 한 번
Yes, and don't ask again this session	a	이 세션 동안 매칭되는 호출 전부
Yes for this project	p	<project>/.snowpea/settings.json 에 허용 규칙으로 저장
No	n	거절

1. 한 번 승인하려면 커서가 Yes 에 있을 때 Enter 를 누릅니다.
2. 프롬프트가 떠 있는 동안에는 승인 메뉴가 키보드를 독점합니다.
3. 타이핑한 문자는 뒤의 초안으로 전달되지 않고 Shift+Tab 은 모드를 바꾸지 않습니다.
4. 아무 입력이 없으면 approvals.timeoutSec(기본 300초) 뒤에 거절로 처리되고 턴이 끝납니다.

모든 결정은 타임아웃을 포함해 $SNOWPEA_HOME/logs/approvals.jsonl 에 기록됩니다.

반복 승인하는 명령은 허용 목록에 추가할 수 있습니다. 패턴은 /allow ^git (status|diff|log)\b 처럼 앵커를 걸고 좁게 작성합니다. ^git 하나로는 git push --force 까지 허용됩니다.

1.5 diff 리뷰

The diff review panel: a unified diff with added and removed lines coloured, the file path header, and the accept / reject footer.

diff 리뷰는 파일 변경이 발생한 위치에 표시되는 통합 diff입니다. 머리글에는 파일 경로와 (+4 −2) 가 표시되고 추가·삭제 줄에는 색이 붙습니다. 새 파일은 ✚ Created notes.md (7 lines) 로 표시됩니다.

긴 패치는 열두 줄에서 잘립니다. 살아 있는 영역에 있는 동안에는 Ctrl+O 로 가장 최근 diff를 펼칠 수 있습니다.

1. accept 모드에서는 파일 편집이 승인 질문 없이 적용되므로 표시된 diff를 읽습니다.
2. 변경을 되돌리려면 다음 프롬프트로 되돌리라고 요청하거나 git checkout 을 실행합니다.
3. 편집마다 승인이 필요하면 plan 모드로 전환합니다.

plan 모드에서는 write 가 거부됩니다.

1.6 모드 전환

The mode switcher open, showing plan / accept / auto with the one-line description of each.

모드 전환기는 다음 턴의 권한 모드를 선택하는 컨트롤입니다. Shift+Tab 은 accept → auto → plan 순서로 순환합니다. 특정 모드를 선택하려면 입력에서 ↓ 를 눌러 히스토리 끝을 지나 모드 요약 줄로 이동한 뒤 Enter 를 누릅니다.

모드	read	write	exec	network	send
plan	허용	거부	거부	허용	거부
accept (기본)	허용	허용	질문	질문	질문
auto	허용	허용	허용	허용	허용

조작	결과
Enter	highlight된 모드 선택
Esc	현재 모드 유지
/mode save	현재 모드를 프로젝트 기본값으로 저장

생각만 요청할 때는 plan을 사용합니다. 일반 작업에는 accept를 사용합니다. 감시 중이거나 버려도 되는 컨테이너에서는 auto를 사용할 수 있습니다.

1.7 슬래시 명령 팔레트

The slash-command palette filtered, showing command names and their one-line help.

슬래시 명령 팔레트는 빈 입력에서 / 를 입력하면 열리는 명령 목록입니다. 명령 이름과 한 줄 도움말이 표시되고 입력을 계속하면 목록이 필터링됩니다. 목록은 데몬이 제공하므로 플러그인이 추가한 명령도 포함됩니다.

명령	하는 일
/mode, /plan, /accept, /auto	모드 보기·바꾸기
/resume, /sessions	저장된 세션 열기
/compact [지시]	대화를 요약해 컨텍스트를 비웁니다
/approvals	무인 승인 대기열
/allow, /allowlist	허용 규칙 추가·확인
/agent list, /team ...	에이전트와 팀
/attach <path>, /voice, /rec, /tts on	첨부와 음성
/update	업데이트 확인·설치
/help	전체 목록

1. 명령을 찾으려면 빈 입력에서 / 를 입력합니다.
2. 전체 목록과 키 표를 보려면 /help 또는 F1 을 사용합니다.
3. 명령과 서브커맨드의 전체 레퍼런스는 명령 문서를 확인합니다.

데스크톱 앱에서 사용하기

데스크톱 앱은 같은 데몬에 연결되는 클라이언트입니다. 같은 SNOWPEA_HOME 을 쓰는 클라이언트는 하나의 데몬과 하나의 세션 집합을 공유합니다. 터미널에서 시작한 세션은 앱 사이드바에 표시되고, 앱에서 시작한 스레드는 TUI에서도 표시됩니다.

항상 표시되는 영역은 왼쪽 레일, 하단 상태 표시줄, 명령 팔레트입니다.

영역	조작 또는 표시
왼쪽 레일	Ctrl/⌘ 1…9 로 이동, Ctrl/⌘ B 로 접기
하단 상태 표시줄	연결 여부, 합의된 프로토콜 버전, 테마, 열린 스레드의 토큰 합계
명령 팔레트	어디서든 Ctrl/⌘ K 로 열기

2.1 첫 실행 마법사

The first-run welcome screen before any provider is configured.

첫 실행 마법사는 프로바이더가 하나도 설정되지 않은 상태에서 앱을 처음 열면 표시되는 설정 화면입니다. 터미널의 설정 마법사와 같은 작업을 수행하고 같은 settings.json 에 씁니다.

1. 벤더를 선택합니다.
2. API 키를 입력하거나 Log in 을 눌러 브라우저 로그인을 시작합니다.
3. 나중에 다시 설정하려면 /setup 을 실행합니다.

터미널과 데스크톱 앱 중 어느 쪽에서 설정해도 같은 설정이 사용됩니다.

2.2 메인 창 (스레드)

The main IDE window: thread list on the left, a finished turn with a user prompt, a tool call and an assistant answer, the context panel on the right.

메인 창은 라우트 / 의 기본 화면입니다. 왼쪽 패널에는 프로젝트와 그에 속한 스레드가 표시되고, 가운데 패널에는 대화가 표시되며, 오른쪽 패널에는 Inspector가 표시됩니다. 답변이 스트리밍되는 동안 가운데 패널에는 텍스트가 표시되고 툴 호출은 인자와 함께 카드로 쌓입니다.

스레드는 항상 작업 디렉터리에 속합니다. 설치 직후에는 Open project… 로 프로젝트를 엽니다.

키	동작
Enter	전송
Shift+Enter	줄바꿈
빈 입력창에서 /	명령 팔레트
Ctrl/⌘ .	실행 중인 턴 중단
Ctrl/⌘ V	클립보드 이미지 첨부, 없으면 텍스트 붙여넣기

1. Open project… 로 프로젝트를 엽니다.
2. 입력창에 프롬프트를 입력하고 Enter 를 눌러 보냅니다.
3. 오른쪽 Inspector에서 이 턴이 읽은 항목과 변경한 항목을 확인합니다.
4. 파일을 첨부하려면 입력창 아래 도구 줄의 📎 를 선택합니다.
5. 받아쓰기를 사용하려면 입력창 아래 도구 줄의 마이크 를 선택합니다.

2.3 스레드 사이드바

The thread sidebar with several sessions, their titles, relative times and the new-thread control.

스레드 사이드바에는 여러 세션이 제목과 상대 시간과 함께 표시됩니다. 맨 위에는 새 스레드를 만드는 컨트롤이 있습니다. 각 스레드에는 생성 표면을 나타내는 ide, tui, gateway, core 배지가 붙습니다.

1. 스레드를 클릭해 전체 기록을 다시 재생합니다.
2. 같은 폴더에 새 스레드를 만들려면 헤더의 + thread 를 선택합니다.

해당 창이 스레드 이벤트를 본 적이 없어도 전체 기록을 다시 재생할 수 있습니다.

2.4 diff 리뷰

The diff review screen: file list, side-by-side diff, per-hunk accept and reject.

데스크톱 diff 리뷰는 라우트 /thread/:id/diff 에서 여는 변경 검토 화면입니다. 왼쪽에는 바뀐 파일 목록이 표시되고, 가운데에는 나란히 놓인 diff가 표시됩니다. 각 hunk에는 accept 또는 reject 결정을 적용할 수 있습니다.

1. 왼쪽 파일 목록에서 파일을 선택합니다.
2. 가운데 diff에서 hunk를 확인합니다.
3. 받을 hunk는 accept를 선택합니다.
4. 받지 않을 hunk는 reject를 선택합니다.

결정은 데몬으로 전달되고 같은 세션을 보는 다른 클라이언트에도 반영됩니다.

2.5 에이전트

The agents/teams screen: named agents, their status and their current task.

에이전트 화면은 라우트 /agents 에 있습니다. 화면은 정의, 실행 중인 서브에이전트, 이름 있는 에이전트의 세 구역으로 구성됩니다. 정의 목록은 데몬의 목록이므로 터미널에서 /agent create 로 만든 정의도 표시됩니다.

실행 중인 서브에이전트 구역은 실시간으로 갱신됩니다. 어떤 세션에서든 서브에이전트가 생성되면 표시되고, 실행 중에는 상태가 바뀌며, 종료 뒤에는 결과를 읽을 수 있습니다.

1. Create agent 를 선택합니다.
2. 에이전트의 목적을 한 문장으로 입력합니다.
3. 채팅에서 호출할 수 있는 이름으로 등록하려면 Named agent 를 체크합니다.
4. 스레드를 거치지 않고 서브에이전트를 시작하려면 각 카드의 작업 입력 상자에 작업을 입력하고 Spawn 을 선택합니다.

데몬은 입력한 한 문장에서 에이전트 정의를 만듭니다.

2.6 스케줄

The scheduler screen: jobs with their cron expression, next run and delivery channel.

스케줄 화면은 라우트 /schedule 에 있습니다. 데몬이 스스로 실행하는 작업과 결과가 실시간 피드로 표시됩니다. 각 행에는 cron 표현식 또는 in 60s 같은 일회성 지정, 다음 실행 시각, 결과가 전달될 채널이 표시됩니다.

항목	의미
Spec	실행 시점. 일회성이면 in 60s, 반복이면 cron
Task	실행할 프롬프트
Mode	작업 세션의 권한 모드 (plan / accept / auto)
Channel	결과가 갈 곳: log, 또는 telegram:<chat id>
Workdir	실행 위치. 비우면 데몬의 홈

무인으로 실행되는 작업은 자기 승인에 스스로 답할 수 없습니다. 예약 작업의 안전한 기본값은 plan 입니다. 예약 작업에서 auto 는 모든 허용 권한을 적용합니다.

2.7 스킬

The skills browser with registry results and an installed-skill badge.

스킬 화면은 라우트 /skills 에 있습니다. 이 화면에서 마켓플레이스를 검색하고 검색 결과를 설치합니다. 이미 설치된 항목에는 배지가 붙고 각 결과에는 출처가 표시됩니다.

검색 후에는 네 가지 상태 중 하나가 표시됩니다.

상태	의미
결과 목록	일치하는 항목이 있음
출처 알림	닿지 못한 출처가 있음
no match	모든 출처가 답했지만 일치가 없음
오류	검색 자체가 실패함

1. 검색어를 입력합니다.
2. Search 를 선택합니다.
3. 설치할 행에서 Install 을 선택합니다.

설치는 데몬을 통해 이루어지므로 설치한 스킬은 TUI에서도 바로 사용할 수 있습니다.

2.8 설정 — 프로바이더

Settings → Providers: the configured vendor, the model picker and the key state.

프로바이더 설정 화면은 라우트 /settings/providers 또는 Ctrl/⌘ , 에 있습니다. 표에는 데몬이 아는 열한 개 벤더와 설정 여부가 표시됩니다. Configure 는 API 키, 기본 URL, 기본 모델을 입력하는 대화 상자를 엽니다.

일부 벤더에는 Log in 이 함께 표시됩니다. Log in 은 API 키 대신 브라우저 로그인 절차를 실행합니다.

비밀 값은 한 방향으로만 흐릅니다. 설정을 다시 읽으면 실제 값 대신 *** 가 오고, Configure 대화 상자는 항상 빈 상태로 시작합니다. 이 동작은 마스킹된 값이 실제 자격 증명을 덮어쓰지 않도록 합니다.

1. 기본으로 사용할 벤더를 설정합니다.
2. 필요하면 모델 피커에서 기본 모델을 변경합니다.
3. 프로젝트 기본값을 바꾸려면 같은 설정 화면의 다른 구역에서 기본 모드와 셸 허용 목록을 설정합니다.

프로젝트 기본값은 해당 프로젝트의 .snowpea/settings.json 에 저장됩니다.

다음 문서 고르기

• 터미널 UI 매뉴얼 — 키 전체 표, 전체 화면 모드, 팀과 짧은 위임.
• 데스크톱 매뉴얼 — 화면별 상세, 워크트리, 메모리, 테마, 패키징.
• FAQ · 문제 해결.

다음 단계

터미널 자세히 보기키와 모드를 확인합니다.→데스크톱 앱 보기화면별 기능을 확인합니다.→문제 해결하기증상별 해결 방법을 확인합니다.→