터미널 UI

터미널 UI (Terminal UI, TUI)

Docker Agent의 기본 인터페이스는 파일 첨부, 테마, 세션 관리 등을 갖춘 풍부한 대화형 터미널 UI예요.

출처: 문서

본문

Docker Agent의 기본 인터페이스는 파일 첨부, 테마, 세션 관리 등을 갖춘 풍부한 대화형 터미널 UI예요.

TUI 시작하기 (Launching the TUI)

전체 TUI와 lean TUI 둘 다 채팅이 비어 있을 때 시작 시 중앙 정렬된 ASCII 아트 Docker Agent 배너를 표시해요. 에이전트가 응답을 시작하거나 커스텀 환영 메시지가 구성되면 배너는 자동으로 숨겨져요.

# Launch with a config
$ docker agent run agent.yaml

# Start with an initial message
$ docker agent run agent.yaml "Help me refactor this code"

# Auto-approve all tool calls
$ docker agent run agent.yaml --yolo

# Enable debug logging
$ docker agent run agent.yaml --debug

# Override the application name shown in the status bar and window title
$ docker agent run agent.yaml --app-name "My Project"

# Preselect a color theme
$ docker agent run agent.yaml --theme dracula

# Hide the sidebar (cannot be re-enabled via Ctrl+B)
$ docker agent run agent.yaml --sidebar = false

# Disable specific slash commands
$ docker agent run agent.yaml --disable-commands = "/cost,/eval,/model"

# Open in read-only mode to review a past session without sending new messages
$ docker agent run agent.yaml --session -1 --session-read-only

# Use the lean TUI for this run
$ docker agent run agent.yaml --lean

Lean TUI

lean TUI는 최소한의 크롬으로 단순화된 터미널 인터페이스를 사용해요. 대화형 실행의 기본값으로 만들려면 사용자 구성에서 lean을 설정하세요:

# ~/.config/cagent/config.yaml
settings:
  lean: true

lean을 생략하거나 false로 설정하면 전체 TUI가 기본값으로 유지돼요. 단일 실행에는 여전히 --lean을 쓸 수 있고, settings.lean이 활성화된 경우 --lean=false로 전체 TUI를 쓸 수 있어요. 플래그와 사용자 구성 간 전체 우선순위 규칙은 User Settings 참조.

lean TUI는 에이전트 실행 중 steering과 follow-up을 지원해요. Enter를 눌러 진행 중인 턴을 steer하거나, Alt+Enter로 현재 턴이 끝난 후 별도 턴으로 메시지를 큐잉해요. 보류 메시지는 라이브 스트림 끝에 흐린 스타일로 나타나요.

lean TUI는 한정된 슬래시 명령 집합을 지원해요: /new, /compact, /model, /effort, /clear, /help, /exit(별칭: /quit), 그리고 에이전트 정의 명령. /model(또는 /model <provider/model>)을 입력해 활성 모델을 인라인으로 전환해요 — 명령은 퍼지 검색 가능한 사용 가능한 모델 목록을 열어요.

슬래시 명령 (Slash Commands)

세션 중 /를 입력하면 사용 가능한 명령을 보고, Ctrl+K를 누르면 명령 팔레트가 열려요:

명령	설명
`/new`	새 대화 시작
`/clear`	현재 대화 지우기(세션 유지, 메시지 드롭)
`/compact`	대화 기록 요약·컴팩션
`/fork`	현재 세션을 새 브랜치로 포크
`/copy`	전체 대화를 클립보드에 복사
`/copy-last`	마지막 어시스턴트 메시지만 클립보드에 복사
`/undo`	최신 스냅샷에서 파일 변경 복원(스냅샷 활성화 시에만)
`/snapshots`	캡처된 스냅샷 나열(스냅샷 활성화 시에만)
`/export`	세션을 HTML로 내보내기
`/sessions`	과거 세션 탐색·로드
`/plans`	플랜 탐색·관리: 모든 공유 플랜과 현재 세션의 session plan. 필터, 상세 보기 열기, 새로 고침, 파일로 내보내기, 그리고 공유 플랜에 대해 status 설정, `$VISUAL` / `$EDITOR`에서 편집·생성, 삭제 — 모두 동시 편집에 대해 보호돼요. lean TUI에서는 사용 불가
`/model`	현재 에이전트의 모델 변경
`/effort`	현재 모델의 추론 노력 수준 설정(`/effort <none\|minimal\|low\|medium\|high\|xhigh\|max>`, 또는 `/effort`만으로 지원 수준 중 선택; 추론 모델 전용). `/effort` 후 공백과 Tab을 눌러 현재 모델이 지원하는 수준을 완성
`/settings`	외관, 동작, 알림 선호 관리
`/yolo`	자동 도구 호출 승인 토글
`/title`	세션 제목 설정 또는 재생성
`/attach`	메시지에 파일 첨부
`/shell`	셸 열기
`/star`	현재 세션 별표/별표 해제
`/context`	컨텍스트 윈도우 분해 표시: 카테고리별 추정 토큰(system prompt, tool definitions, prompt files, messages, tool results, compaction summary), 팀 수준 Live sessions 보기(현재 세션 + 에이전트, 짧은 세션 ID, 컨텍스트 예산을 가진 모든 실행 중 하위 에이전트 세션), 첨부 파일과 프롬프트 파일의 파일별 인벤토리. 컴팩션이 발생했으면 대화상자는 가장 최근 컴팩션 요약의 원문 텍스트도 표시. 전용 `compaction_model`이 기본 모델 자체 윈도우 아래로 유효 한도를 제한하면 두 번째 줄에 "compaction cap: • tokens"로 표시 — Live-sessions 행은 cap에 대해 조용하고, 사이드바는 모델·수치를 반복하지 않는 최소 ⚠ capped 마커를 보여줘요(`/context` 헤더가 모델+숫자의 권위 있는 소스). 화살표 키로 행 선택: 라이브 세션에서 Enter를 눌러 명시적 컴팩션, 첨부 파일에서 d를 눌러 드롭
`/drop`	세션 컨텍스트에서 첨부 파일 제거(`/drop <path>`, 또는 `/drop`만으로 `/context` 대화상자에서 검토·드롭). `/drop` 후 공백과 Tab을 눌러 첨부 파일 경로 완성
`/cost`	이 세션의 비용 분해 표시. By Agent 섹션(By Model 옆)으로 에이전트별 누적 비용 표시. 귀속되지 않은 사용과 컴팩션 지출은 자체 버킷으로.
`/eval`	평가 보고서 생성
`/pause`	런타임 루프 일시 중지/재개. 에이전트가 요청 중이면 진행 중 요청이 완료될 때까지 리사이즈 핸들이 "Pausing…" 표시. 루프가 차단되면 표시기가 "⏸ Paused"로 바뀌어요. `/pause`를 다시 실행해 재개.
`/tools`	모든 도구셋(라이프사이클 상태 포함)과 그들이 노출하는 도구 표시
`/skills`	현재 에이전트가 사용 가능한 스킬 나열
`/toolset-restart`	명명된 도구셋의 감독자 주도 재연결 강제(`/toolset-restart <name>`). `/toolset-restart` 후 공백과 Tab을 눌러 도구셋 이름 완성; 재시작 불가 도구셋은 흐리게 표시되고 선택 불가
`/permissions`	도구 권한 규칙 검사·편집
`/speak`	시스템 음성-텍스트로 음성 입력(macOS 전용)
`/exit`	애플리케이션 종료(별칭: `/quit`, `/q`)

슬래시 명령(내장·명명 둘 다)은 입력 시 즉시 실행돼요. 에이전트가 작업 중일 때 보내진 일반 채팅 메시지는 기본적으로 진행 중인 스트림으로 steer돼요: 에이전트가 턴 도중에 집어들어요(에이전트가 보는 지점의 트랜스크립트에 나타남) — 스트림을 끊지 않고요. 이전의 턴 끝 동작을 선호하나요? /settings의 Behavior 탭에서 While agent is working을 Queue로 전환하세요. 큐잉된 메시지는 스트림이 멈추면 순서대로 처리돼요.

에이전트 정의 명령(프롬프트, URL 링크, 에이전트 전환 단축키)은 에이전트 YAML의 commands: 아래에 구성돼요 — --disable-commands로 명령을 숨기는 방법을 포함한 전체 참조는 Custom Commands 참조.

에이전트 패널 (Agents Panel)

사이드바의 Agents 섹션은 팀의 모든 에이전트를 나열하고 /settings의 Sidebar info mode로 선택할 수 있는 두 가지 표시 모드가 있어요:

Compact (기본값) — 현재 에이전트는 포커스 카드로 표시(목록의 위치에 제자리 렌더링)되고 이름, 줄바꿈된 설명, 전체 provider/model, thinking 줄을 담아요. 다른 모든 에이전트는 컴팩트한 두 줄 행으로 표시 — 1행은 단축키/스피너, 에이전트 이름(강조 색), 오른쪽 정렬 thinking 게이지; 2행은 들여쓰기된 전체 provider/model와, 에이전트가 실행된 후에는 컨텍스트 윈도우의 오른쪽 정렬 백분율로 표시되는 최신 컨텍스트 사용.
Detailed — 각 에이전트는 단일 줄(좁은 사이드바 폭에서는 여러 줄로 분할)에 레이블된 Effort, Context, Cost 메트릭이 있는 반응형 카드로 표시되어 팀 전체에서 에이전트별 누적 비용을 한눈에 볼 수 있어요.

에이전트는 빈 줄로 구분되어 행이 시각적으로 구별돼요. effort 게이지는 thinking의 유일한 시각 언어예요. 포커스 카드와 Agent Inspector가 옆에 정확한 수준을 풀어써요. 어떤 에이전트든 왼쪽 클릭으로 전환해요.

큰 팀에서는 명단을 지금 중요한 에이전트로 줄일 수 있어요: /settings → Appearance → Sidebar sections 아래 Agents에 중첩된 Active agents only(기본 꺼짐)를 켜면 현재 세션에서 활성인 에이전트만 나열해요 — 선택되었거나 작업 중인 에이전트, 진행 중인 전송의 참가자, 기록된 참여(사용 또는 귀속 비용, 재로드된 세션으로 복원된 에이전트 포함)가 있는 어떤 에이전트. 필터는 top/bottom 밴드에도 적용되고 순전히 현재 표시용이에요 — Ctrl+숫자 단축키는 원래 팀 위치를 유지하고 에이전트 순환은 여전히 전체 팀을 순환해요 — 그리고 Agents 섹션 자체가 숨겨져 있으면 사용 불가.

에이전트 검사기 (Agent inspector)

읽기 전용 Agent Inspector를 열어 어떤 에이전트의 전체 구성을 라이브 상태와 함께 검사할 수 있어요. instruction/system prompt는 의도적으로 생략되고, 에이전트가 선언하는 다른 모든 것이 표시돼요:

에이전트(카드 또는 행)를 오른쪽 클릭하면 전환 없이 검사기가 열려요.
Ctrl+왼쪽 클릭도 동일 — 오른쪽 클릭을 전달하지 않는 터미널용 폴백.
왼쪽 클릭은 항상 에이전트로 전환해요.

제목은 에이전트의 강조 색으로 렌더링돼요. 섹션은 이 순서로 나타나고 빈 섹션은 생략돼요:

Description — 에이전트의 줄바꿈된 설명.
Live state — 검사 중인 에이전트가 현재 실행 중이면 ● current agent 줄.
Model / Fallback / Thinking — provider/model, 폴백 모델들, 게이지 + 값 thinking 줄(선택 가능한 thinking이 없는 모델 — 예: harness 지원 에이전트 — 에서는 생략).
Context — 에이전트의 최신 알려진 컨텍스트 사용(예: Context: 12.8K of 128.0K tokens (10%); 컨텍스트 한도를 알 수 없으면 단순 토큰 수, 에이전트가 실행되기 전까지 생략). 하위 에이전트와 백그라운드 에이전트 실행이 포함돼요. 전용 compaction_model이 기본 모델 자체 윈도우 아래로 유효 한도를 제한하면 토큰 사용 줄에 짧은 "⚠ capped" 마커도 표시(/context에서 모델과 수치 확인).
Cost — 세션 트리 전체 실행의 에이전트 누적 비용. 반복 세션 스냅샷은 이중 계산되지 않아요. 에이전트가 실행되기 전까지 생략.
Sub-agents (N) / Handoffs (N) / Skills (N) — 대화상자 폭으로 줄바꿈된 컴팩트한 인라인 쉼표 구분 목록.
Limits — 설정된 구성된 에이전트별 한도(예: Limits: max-iter 50 · history 40 · max-tool-calls 5).
Options — 활성화된 옵션 플래그(예: Options: add-date · add-environment-info · redact-secrets).
Toolsets (N) — 상태 마커, 이름, 종류, 도구 수가 있는 toolset당 한 줄, 이어서 들여쓰기된 도구 이름.
Commands (N) — 에이전트가 정의하는 슬래시 명령, 각각 설명 포함.

각 toolset은 라이브 라이프사이클을 반영하는 단일 폭 상태 마커를 담아요: ● started(서빙 중), ○ stopped(아직 시작 안 됨), ⚠ error. toolset 아래 나열된 도구는 시작됐을 때의 라이브 도구 이름이에요. 시작되지 않은 toolset의 경우 검사기는 대신 선언된 도구를 보여줘요: declared: 접두사가 있는 allow-list(도구셋이 allow-list를 선언하지 않아 모든 도구를 서브하면 아무것도 표시 안 함). 이렇게 하면 에이전트가 무엇으로 구성됐는지와 실제로 무엇이 실행 중인지, 에이전트를 사용하기 전에도 둘 다 볼 수 있어요.

콘텐츠가 길면 대화상자가 스크롤되고 Esc로 닫아요. 원격 런타임(로컬 팀 구성을 보유하지 않음)은 우아하게 저하돼요 — 구성 파생 섹션은 그냥 생략돼요.

2행의 모델 식별자는 넘칠 때만 왼쪽에서 잘려요(예: …claude-sonnet-4-6) — 정보를 주는 꼬리(변형/버전)가 보존되도록요. 사이드바가 좁아지면 모델은 자체 줄을 유지하고, 최소 폭 근처에서는 1행의 게이지가 이름을 읽을 수 있게 단일 셀로 접혀요.

각 모델의 thinking 상태는 카드의 게이지 + 값, 행의 게이지 또는 배지로 표시돼요(✻ 글리프 없음):

모델 상태	카드 줄	행 배지
Effort level	thinking ▰▰▰▰▱▱ high	▰▰▰▰▱▱ (effort 게이지)
Adaptive budget	thinking auto adaptive	auto
Token budget	thinking ◉ 8.2K tokens	◉ 8.2K
비활성화(가능)	thinking ▱▱▱▱▱▱ off (흐림)	▱▱▱▱▱▱ (빈 게이지)
추론 불가능	(생략)	(생략)

effort 게이지는 고정 폭 6셀 표시기(▰ 채움, ▱ 빔)라서 배지 열이 정렬을 유지해요. 선택 가능한 여섯 수준을 채워진 셀 수에 일대일 매핑해요 — minimal → ▰▱▱▱▱▱, low → ▰▰▱▱▱▱, medium → ▰▰▰▱▱▱, high → ▰▰▰▰▱▱, xhigh → ▰▰▰▰▰▱, max → ▰▰▰▰▰▰ — 셀 수만으로 무손실이고, low→high 색 램프가 보조 단서예요. 가능하지만 비활성인 모델은 흐린 빈 게이지(▱▱▱▱▱▱ off)를 보여주고, adaptive 예산은 auto, 토큰 예산은 ◉ <count>를 유지해요. 같은 게이지 + 값이 포커스 카드, Agent Inspector, 행에 렌더링돼요.

Harness 지원 에이전트(예: claude-code)는 모델로 harness 유형을 보여주고 thinking 게이지가 없어요. Shift+Tab으로 현재 모델의 thinking-effort 수준을 순환해요. ✻ Thinking: 토스트가 변경을 확인해줘요(사이드바가 숨겨졌을 때 유용).

에이전트 위임 피드백 (Agent Delegation Feedback)

부모 에이전트가 transfer_task를 호출해 하위 에이전트에 작업을 위임하면 TUI는 사이드바와 채팅 둘 다에서 라이브 시각 피드백을 제공해요.

사이드바 — Transfer 상자: 위임이 시작되는 즉시 에이전트 명단 아래에 이동하는 점으로 핸드오프 방향을 보여주는 애니메이션 Transfer 상자가 나타나요:

╭─ Transfer ─────────────────╮
│ parent ●──────► child      │
╰────────────────────────────╯

상자는 최소 1.5초 동안 보여요. 하위 에이전트가 첫 메시지·추론·도구 출력을 내면 상자는 숨겨져요(최소 시간은 여전히 존중) — 사이드바가 활성 에이전트에 집중하게 해요. 하위 에이전트가 느리거나 조용하면 상자는 3초 최대 컷오프 후 숨겨져요. 상자가 숨겨진 후에도 위임이 진행 중이면 헤더가 ↔ 마커를 보여줘요.

사이드바 — Return 상자: 하위 에이전트가 끝나고 제어가 부모로 돌아오면 짧은 Return 상자가 최대 1.5초 동안 반대 방향을 애니메이션하고 사라져요:

╭─ Return ───────────────────╮
│ child ●──────► parent      │
╰────────────────────────────╯

채팅 — 반환 전환: 사이드바 Return 애니메이션과 함께 채팅은 두 에이전트 배지 사이에 한 줄 정적 전환을 보여줘요:

[child] returned control to [parent]

이 전환은 영속되지 않아요 — 세션을 재로드해도 다시 나타나지 않아요.

컨텍스트 사용 게이지 (Context-Usage Gauge)

사이드바 토큰 사용 섹션에 표시된 컨텍스트 백분율과 lean TUI 상태 줄의 채움 막대는 둘 다 활성 세션이 자동 컴팩션 임계값에 접근할수록 색이 단계적으로 높아져요:

상태	색	트리거
정상	(기본)	컴팩션 임계값의 75% 미만 사용
경고	주황	컴팩션 임계값의 75% 이상 사용
위험	빨강	컴팩션 임계값의 95% 이상 사용

컴팩션이 실행되는 동안 백분율은 "compacting…" 표시기로 바뀌고 토큰 수는 lean TUI 상태 줄에서 계속 보여요.

임계값은 에이전트의 구성된 compaction_threshold(기본 0.9)에 비례하므로 커스텀 값도 예측 가능한 시각 여유를 유지해요. 구성 세부 사항은 Compaction Threshold 참조.

사이드바 사용량 읽기의 토큰/컨텍스트 부분(글리프, 토큰 수, 컨텍스트 백분율 — 또는 "compacting…" 마커 — 그리고 ⚠ capped 마커)을 클릭하면 전체 분해와 함께 /context 대화상자가 열려요. 비용 부분($ 수치와 하위 세션 수)을 클릭하면 대신 /cost 대화상자가 열려요. "Token Usage" 섹션 제목 자체는 클릭할 수 없어요.

Thinking과 도구 상세 (Thinking and Tool Details)

추론/thinking 블록은 기본적으로 접혀 있고 Thinking 헤더 배지를 담아요. 접혀 있을 때 TUI는 짧은 미리보기와 컴팩트한 도구 요약을 보여줘요. 블록을 펼치면 전체 thinking 콘텐츠와 실제 도구 렌더러(파일 편집 diff 같은 상세 도구 출력 포함)가 보여요.

thinking/도구 블록을 기본 펼침으로 새 세션을 시작하려면 사용자 구성에서 expand_thinking을 설정하세요:

# ~/.config/cagent/config.yaml
settings:
  expand_thinking: true

false로 설정하거나 생략하면 기본 접힘 동작을 유지해요. 전체 설정 참조는 User Settings 참조.

Mermaid 다이어그램 (Mermaid Diagrams)

TUI는 Mermaid 다이어그램 블록을 원시 문법 대신 인라인으로 렌더링해요. 어시스턴트 메시지가 ```mermaid 로 태그된 펜스 코드 블록을 담으면 TUI는 다이어그램을 파싱하고 ASCII 표현을 대화에 직접 그려요:

다이어그램 유형	지원
`graph` / `flowchart`	✅ 인라인 렌더링
`sequenceDiagram`	✅ 인라인 렌더링
`stateDiagram` / `stateDiagram-v2`	✅ 인라인 렌더링(`direction TD/TB/BT/LR/RL` 지원)
기타 유형(`classDiagram`, `erDiagram`, …)	구문 강조 코드 블록으로 폴백

Mermaid 렌더링은 전체 TUI와 lean TUI 둘 다에서 동작해요. 지원되지 않거나 구문 오류가 있는 다이어그램 블록은 일반 펜스 코드 블록으로 표시돼요 — 구성이 필요 없고 비활성화할 방법도 없어요.

LaTeX 수학 렌더링 (LaTeX Math Rendering)

TUI는 LaTeX 수학 표현식을 터미널 친화적인 Unicode 텍스트로 렌더링해요. 어시스턴트 메시지가 인라인 수학( $…$ 로 구분)이나 디스플레이 수학($$…$$로 구분)을 담으면 TUI는 지원되는 LaTeX 명령을 Unicode 등가물로 변환해 대화에 직접 표시해요.

지원되는 기능:

그리스 문자(\alpha, \beta, \gamma, …)
수학 연산자(\times, \div, \pm, \oplus, …)
관계(\le, \ge, \approx, \equiv, …)
집합 연산자(\cap, \cup, \subset, \in, …)
미적분 기호(\int, \sum, \prod, \partial, \nabla, …)
화살표와 논리(\to, \implies, \forall, \exists, …)
위첨자·아래첨자(예: x^2, a_i)
분수(\frac{a}{b}), 제곱근(\sqrt{x}), 행렬
일반 함수(\sin, \cos, \log, \lim, …)

지원되지 않거나 구문 오류가 있는 LaTeX 표현식은 원시 소스를 표시하는 것으로 폴백해요. LaTeX 렌더링은 전체 TUI와 lean TUI 둘 다에서 동작하고 구성이 필요 없으며 비활성화할 수 없어요.

Markdown 이미지 (Markdown Images)

TUI는 에이전트 응답에서 참조된 이미지를 Kitty 그래픽 프로토콜로 가져와 렌더링해요. 어시스턴트 메시지가 표준 Markdown 이미지 참조를 담으면 TUI는 이미지를 백그라운드로 다운로드하고 참조 지점에 인라인으로 표시해요. 이미지가 로드되는 동안 플레이스홀더가 표시되고, 로드되면 이미지가 제자리에 놓인 상태로 메시지가 다시 렌더링돼요.

오직 http://, https://, data:image/…;base64,… URI만 해결돼요. file://, sandbox://, 그리고 다른 URI 스킴은 로컬 파일을 읽을 수 있는 프롬프트 주입 공격에 대한 보안 조치로 거부돼요. 베어 상대 경로(예: ./output.png, 에이전트 생성 이미지용)는 로컬 파일시스템을 통해 읽혀요. 로드에 실패한 이미지는 조용히 드롭돼요 — 주변 메시지 텍스트는 영향받지 않아요. 이미지 렌더링은 Kitty 그래픽 프로토콜을 지원하는 터미널이 필요하고, 터미널이 지원하지 않으면 자동으로 비활성화돼요. ~/.config/cagent/config.yaml의 render_images: false나 /settings의 Render images 토글로 명시적으로 비활성화할 수도 있어요.

스냅샷, `/undo`, `/snapshots`

~/.config/cagent/config.yaml에서 shadow-git 스냅샷을 전역으로 활성화해요:

settings:
  snapshot: true

활성화하면 Docker Agent는 턴 경계에서 파일시스템 스냅샷을 기록해요. TUI는 그 스냅샷에 작동하는 두 개의 슬래시 명령을 노출해요:

/undo — 가장 최근 스냅샷에서 파일 복원(한 단계 뒤로).
/snapshots — 캡처된 스냅샷 수와 각각의 파일 수를 보여주는 대화상자 열기. ↑/↓(또는 j/k)로 항목을 강조한 다음 r을 눌러 워크스페이스를 그 시점으로 재설정해요. <original>을 선택하면 모든 스냅샷을 되돌리고 워크스페이스를 에이전트 이전 상태로 되돌려요. Esc는 아무것도 바꾸지 않고 대화상자를 닫아요.

어느 명령도 세션 트랜스크립트에서 메시지를 제거하지 않아요 — 오직 디스크의 파일만 건드려요. 두 명령(및 해당 명령 팔레트 항목)은 스냅샷이 꺼져 있으면 숨겨져요. snapshot을 생략하거나 false로 설정하면 자동 스냅샷을 끈 채로 두고, 에이전트는 여전히 스냅샷 훅을 수동으로 구성할 수 있어요.

shadow-git 메커니즘이 어떻게 동작하고 에이전트별로 어떻게 연결하는지는 Snapshots 참조.

파일 첨부 (File Attachments)

@ 트리거로 메시지에 파일 내용을 첨부해요:

@를 입력해 파일 완성 메뉴 열기
타이핑을 시작해 파일 필터(.gitignore 존중)
파일을 선택해 참조 삽입

# In the chat input:
Explain what the code in @pkg/agent/agent.go does

에이전트는 구조화된 <attachments> 블록의 전체 파일 내용을 받는 반면, UI는 참조만 보여줘요.

크거나 자주 재사용하는 문서, 또는 TUI 대신 API나 chat server를 통해 에이전트에 콘텐츠를 가져오려면 Choosing a Large-Input Strategy 참조.

첨부 파일은 세션에도 기록되어 작업 전송으로 생성된 하위 에이전트가 읽을 수 있어요. 무엇이 첨부됐는지 검토하려면 /context를 열어요: 대화상자는 각 첨부 파일(및 해결된 프롬프트 파일)을 파일별 토큰 추정과 함께 나열하고, 컴팩션이 발생했으면 가장 최근 컴팩션 요약의 원문 텍스트를 표시해요. ↑/↓로 첨부 파일을 선택하고 d(또는 x/Del)를 눌러 드롭하거나, /drop <path>를 직접 실행해요 — /drop 후 공백과 Tab을 눌러 현재 첨부 파일에서 경로를 완성. 드롭은 하위 에이전트와 스킬과 파일 공유를 중단해요. 이전 메시지에 이미 인라인된 콘텐츠는 컴팩션까지 대화에 남아 있고, 파일은 @나 /attach로 언제든 다시 첨부할 수 있어요.

팀 컨텍스트 예산과 목표 컴팩션 (Team Context Budgets and Targeted Compaction)

/context 대화상자는 Live sessions 섹션도 보여줘요: 현재 세션 + 현재 실행 중인 모든 하위 에이전트 세션(task transfer로 생성된 포그라운드 자식과 장수 run_background_agent 작업). 각 행은 에이전트 이름, 짧은 세션 ID(같은 에이전트의 두 동시 실행을 구분 가능하게), 그 세션의 컨텍스트 예산 — 사용된 토큰, 컨텍스트 한도, 백분율, 또는 모델 윈도우를 해결할 수 없을 때 명시적 "limit unknown" 읽기 — 을 보여줘요. Live-sessions 행은 컴팩션 cap 문구를 스스로 반복하지 않아요 — 대화상자 헤더 줄이 어떤 모델(있다면)이 유효 한도를 제한하는지에 대한 유일한 권위예요.

컴팩션이 발생했으면 대화상자는 파일 인벤토리 아래 "Latest compaction summary" 섹션에 가장 최근 컴팩션 요약의 원문 텍스트를 표시해요. 정확히 무엇이 요약됐는지 보여주고, 하드 개행을 보존하고 긴 줄을 대화상자 폭으로 소프트 래핑해요.

↑/↓로 라이브 세션을 선택하고 Enter를 눌러 명시적으로 컴팩션해요. 교차 에이전트 컴팩션은 이 명시적 요청에서만 발생해요: 유휴 트리거 자동 컴팩션은 추가되지 않고, 하위 에이전트 세션의 기존 자동 임계값과 오버플로 복구 컴팩션은 변하지 않아요. 요청은 대상 세션의 자체 런 루프에 큐잉되고 모델 턴 사이의 다음 안전 지점에서 실행되므로 진행 중인 턴을 손상시킬 수 없어요. 대화상자가 닫히고 알림이 요청을 확인하며, 두 번째 알림이 에이전트 이름과 함께 결과(compacted, skipped, failed)를 보고해요. 메인 행을 선택하면 /compact와 같은 컴팩션을 실행해요. /compact 자체는 계속 현재 루트 세션을 컴팩션해요. 원격 런타임은 라이브 세션 추적을 노출하지 않으므로 섹션은 거기서 생략돼요.

런타임 모델 전환 (Runtime Model Switching)

세션 중 /model 또는 Ctrl+M으로 AI 모델을 변경해요. 모델 전환은 전체 TUI와 lean TUI 둘 다에서 동작해요.

Ctrl+M(전체 TUI)을 누르거나 /model(두 TUI)을 입력
구성 모델에서 선택하거나 커스텀 provider/model 입력
모델 전환은 세션에 저장되고 재로드 시 복원돼요

models gateway(--models-gateway)가 구성되고 OpenAI 스타일 /v1/models 엔드포인트를 노출하면 피커는 게이트웨이가 실제로 서브하는 모델(에이전트 구성에 정의된 모델과 병합)을 나열해요. 게이트웨이가 /v1/models를 노출하지 않으면 피커는 일반 카탈로그로 폴백해요.

피커의 카탈로그 항목은 models.dev에서 오고 로컬에 하루 캐시돼요. 피커에서 Ctrl+R을 눌러 models.dev 카탈로그 재가져오기를 포함해 모델 발견을 다시 실행하게 할 수 있어요.

팁: 모델 전환을 사용해 복잡한 작업에는 더 유능한 모델을, 단순한 쿼리에는 더 싼 모델을 시도하세요 — YAML 구성을 수정하지 않고요.

편집 가능한 메시지 (Editable Messages)

이전 사용자 메시지를 아무거나 편집해 대화를 분기해요. 과거 사용자 메시지에 마우스를 올리고 ✎ edit을 클릭(또는 키보드로 선택하고 e를 눌러)해 수정해요 — 에이전트가 그 지점부터 재처리하고, 원래 세션 기록은 보존돼요. 작업을 잃지 않고 대안적 접근을 탐색하는 데 좋아요.

사용자나 어시스턴트 메시지에 마우스를 올리면 ⎘ copy 버튼도 나타나 메시지 텍스트를 클립보드에 복사해요(메시지가 선택되면 c).

오류 복구 (Error Recovery)

에이전트 턴이 실패하면(치명적 모델 오류, 훅 블록, 루프 감지, 도구 설정 실패) TUI는 오류를 메시지 스트림에 표시하고 세션 저장소에 영속해요. 오류는 재로드를 견디고 정확히 발생한 곳에 표시되어 공유·원격 세션에서도 보여요.

각 오류 메시지는 클릭 가능한 ↻ retry 버튼을 포함해요. 클릭하면 마지막 메시지를 다시 타이핑하지 않고 실패 지점에서 대화를 재개해요. 일시적 실패(속도 제한, 네트워크 급증, 모델 API 오류)를 한 번의 클릭으로 복구할 수 있어요.

세션 관리 (Session Management)

Docker Agent는 세션을 자동으로 저장해요. /sessions로 과거 대화를 탐색해요:

검색·필터링으로 과거 세션 탐색. 검색은 세션 제목과 세션 ID(전체 UUID, 대시 없는 변형, 부분 조각 모두 올바르게 해결 — 복사된 ID나 로그에서 세션으로 점프할 때 유용)에 매칭돼요.
워크스페이스 그룹화 — 세션은 git 저장소 루트(worktree 인식)로 그룹화돼요. 같은 저장소의 어떤 하위 디렉토리나 연결된 worktree의 세션도 "This workspace" 아래 함께 그룹화되고, 헤더는 저장소 루트 경로를 보여줘요. 현재 저장소 밖의 세션은 시작 디렉토리와 함께 "Other locations" 아래 나타나요. 브라우저에서 Ctrl+G를 눌러 all, current-workspace 전용, other-directory 보기 사이를 순환해요. 세션 복원은 원래 디렉토리에서 다시 열므로 레이블은 항상 복원이 어디에 놓일지와 일치해요.
/star로 중요한 세션 별표
이전 사용자 메시지를 편집해 대화 분기 — 원래 세션 기록 보존
docker agent run config.yaml --session <id>로 세션 재개
상대 참조 — 마지막 세션은 --session -1, 그 이전은 -2

세션 제목 편집 (Session Title Editing)

세션 제목을 커스터마이즈해 더 의미 있고 찾기 쉽게 해요. 기본적으로 Docker Agent는 첫 메시지에 기반해 제목을 자동 생성하지만, 언제든 재정의하거나 재생성할 수 있어요.

/title 명령 사용:

/title # Regenerate title using AI (based on recent messages)
/title My Custom Title # Set a specific title

사이드바 사용:

사이드바의 세션 제목 옆 연필 아이콘(✎) 클릭
새 제목 입력
Enter로 저장, Escape로 취소

참고: 수동으로 설정한 제목은 보존되고 자동 생성에 덮어쓰이지 않아요. 제목 변경은 즉시 세션에 영속돼요.

키보드 단축키 (Keyboard Shortcuts)

단축키	동작
Ctrl+K	명령 팔레트 열기
Ctrl+M	모델 전환
Ctrl+R	역방향 기록 검색(이전 입력 검색)
Ctrl+G	역방향 기록 검색 취소
Ctrl+S	팀의 다음 에이전트로 순환
Shift+Tab	현재 모델의 thinking-effort 수준 순환(✻ Thinking: 토스트 표시)
Ctrl+1–9	팀 목록에서 에이전트 N으로 직접 전환
Ctrl+T	새 탭 열기(추가 에이전트 세션)
Ctrl+W	현재 탭 닫기
Ctrl+N	다음 탭
Ctrl+P	이전 탭
Ctrl+B	사이드바 토글(전체 UI 모드 전용; `--sidebar=false`일 때 비활성화)
Ctrl+Y	YOLO 모드 토글(도구 호출 자동 승인)
Ctrl+O	도구 결과 숨기기 토글
Ctrl+Z	TUI를 백그라운드로 일시 중지(`fg`로 재개)
Ctrl+X	큐잉된 메시지 지우기
Escape	현재 작업 취소
Enter	메시지 전송(또는 에이전트 실행 중 steer)
Alt+Enter	에이전트 실행 중 후속 턴 큐잉
Shift+Enter	줄바꿈 삽입
Up/Down	메시지 기록 탐색

Ctrl+H를 눌러 모든 사용 가능한 키보드 단축키의 전체 목록을 봐요.

커스텀 키바인딩 (Custom Keybindings)

~/.config/cagent/config.yaml의 settings 블록에 keybindings 목록을 추가해 위 단축키를 리매핑할 수 있어요(User Settings 필드 참조). 각 항목은 동작을 Bubbles 키 형식의 하나 이상의 키 조합에 매핑해요(예: ctrl+q, alt+enter, f2). 나열되지 않은 동작은 기본값을 유지해요.

이것은 VS Code 내부 같은 일반적인 에디터/터미널 단축키와 충돌하는 Ctrl+J 개행 폴백을 대체하는 권장 방법이에요.

settings:
  keybindings:
  # Insert a newline with Alt+Enter instead of Ctrl+J. Shift+Enter still
  # works automatically on terminals that report it.
  - action: "editor_newline"
    keys: [ "alt+enter" ]
  # Allow several keys for one action.
  - action: "commands"
    keys: [ "f2", "ctrl+k" ]
  - action: "quit"
    keys: [ "ctrl+q" ]

유효한 동작:

동작	기본값	설명
`editor_send`	`enter`	현재 메시지 전송
`editor_newline`	`ctrl+j`	입력에 줄바꿈 삽입
`quit`	`ctrl+c`	종료(종료 확인 열기)
`switch_focus`	`tab`	패널 간 포커스 전환
`commands`	`ctrl+k`	명령 팔레트 열기
`help`	`ctrl+h`	도움말 대화상자 표시
`toggle_yolo`	`ctrl+y`	YOLO 모드 토글
`toggle_hide_tool_results`	`ctrl+o`	도구 결과 숨기기 토글
`cycle_agent`	`ctrl+s`	다음 에이전트로 순환
`model_picker`	`ctrl+m`	모델 피커 열기
`clear_queue`	`ctrl+x`	큐잉된 메시지 지우기
`suspend`	`ctrl+z`	TUI 일시 중지
`toggle_sidebar`	`ctrl+b`	사이드바 토글
`edit_external`	`ctrl+g`	외부 에디터에서 입력 편집
`history_search`	`ctrl+r`	증분 기록 검색

줄바꿈용 Shift+Enter는 터미널 기능에서 감지되고 editor_newline과 무관하게 지원되는 곳에서 항상 사용 가능해요.

잘못된 항목은 경고(--debug에서 보임)와 함께 무시돼서 잘못된 구성이 절대 TUI를 깨지 않아요: 알 수 없는 동작, 비었거나 잘못된 키, 다른 동작과 충돌할 키는 드롭되고 다른 모든 바인딩은 계속 동작해요.

기록 검색 (History Search)

Ctrl+R을 눌러 증분 기록 검색 모드에 들어가요. 타이핑을 시작해 이전 입력을 필터해요. Enter로 일치 항목을 선택하거나 Escape로 취소해요.

설정 (Settings)

/settings를 실행해 설정 대화상자를 열어요. Tab으로 Appearance, Behavior, Notifications 사이를 전환해요.

팁 — 전체 설정 참조: 이 섹션은 /settings 대화상자를 다뤄요. 전체 설정 필드 목록(대화상자 UI가 없는 것 — permissions, hooks, keybindings 같은 — 포함)과 CLI 플래그·별칭과 어떻게 상호작용하는지는 User Settings 참조.

Appearance 탭은 테마를 선택하고 레이아웃을 커스터마이즈해요. 레이아웃 변경은 라이브 도식 미리보기를 보여주고 대화상자 뒤의 UI에 즉시 적용돼요:

Sidebar position : Right(기본), Left, Top, Bottom. Left/right는 채팅 옆에 전체 세로 사이드바를 유지하고, top/bottom은 채팅 위나 아래에 컴팩트한 가로 밴드로 렌더링해요(세션 제목, 작업 디렉토리, 토큰 사용, 현재 에이전트와 모델의 한 줄 요약; 멀티 에이전트 구성에서는 모든 팀 에이전트가 현재 에이전트 뒤에 이름으로 나열).
Sidebar info mode : Compact(기본) 또는 Detailed. Agents 패널이 에이전트 행을 렌더링하는 방식을 제어 — agents panel 참조. settings.layout.sidebar_info_mode: detailed로 영속되고 compact는 기본이며 구성에서 생략돼요.
Section spacing : Compact, Normal(기본), Relaxed — 사이드바 섹션 사이의 빈 줄 수(1, 2, 3).
Sidebar sections : Session path(작업 디렉토리 줄, git 브랜치 포함), Token usage, Agents, Tools, Todos 섹션의 가시성 토글. 세션 제목은 항상 표시돼요.

Appearance는 또한 split-diff 렌더링, 확장 thinking, 도구 결과가 기본적으로 숨겨지는지 제어해요. Theme를 선택해 테마 피커를 열어요.

Behavior 탭은 busy-message 처리, auto-approve 기본값, 탭 복원, 자동 스냅샷, lean UI, 최대 탭 제목 길이를 제어해요. Restore-tabs와 lean-UI 변경은 다음 실행에 적용돼요. auto-approve 활성화는 확인이 필요해요.

Notifications 탭은 완료 사운드를 활성화하고 사운드가 재생되기 전 최소 작업 기간을 설정해요.

Enter로 적용·영속하거나 Escape로 취소·이전 레이아웃 복원해요. 설정은 ~/.config/cagent/config.yaml에 전역으로 저장돼요:

# ~/.config/cagent/config.yaml
settings:
  busy_send_mode: queue # steer (default), queue
  layout:
    sidebar_position: left # right (default), left, top, bottom
    sidebar_info_mode: detailed # compact (default, omitted), detailed
    section_spacing: compact # normal (default), compact, relaxed
    hide_session_path: false
    hide_usage: true
    hide_agents: false
    active_agents_only: false # true to filter to session-active agents
    hide_tools: false
    hide_todos: false

테마 (Theming)

내장 또는 커스텀 테마로 TUI 외관을 커스터마이즈해요:

# Open Settings and select Theme under Appearance
/settings

내장 테마 (Built-in Themes)

default, default-light, catppuccin-latte, catppuccin-mocha, dracula, gruvbox-dark, gruvbox-light, nord, one-dark, solarized-dark, tokyo-night

자동 테마 (터미널 매칭) (Auto Theme)

특수 테마 auto는 고정 테마를 명명하는 대신 터미널의 light/dark 배경을 따르는 것이에요. Settings → Appearance → Theme에서 Auto (match terminal)를 선택하거나 --theme auto를 전달하거나 사용자 구성에 설정해요:

settings:
  theme: auto
  theme_dark: default # optional, theme used on dark backgrounds (default: default)
  theme_light: default-light # optional, theme used on light backgrounds (default: default-light)

시작 시 터미널 배경이 (OSC 11로) 조회되어 쌍에서 dark 또는 light 테마를 골라요. 비대화형 실행(파이프, CI)은 dark 테마로 폴백해요. 등장 변화를 보고하는 터미널(DEC mode 2031 — Ghostty, kitty, contour, …)에서는 Docker Agent 실행 중 OS나 터미널 등장을 뒤집으면 테마가 라이브로 전환돼요. 그 모드가 없는 터미널은 창이 포커스를 되찾을 때 재동기화해요.

커스텀 테마 (Custom Themes)

~/.cagent/themes/에 YAML로 테마 파일을 만들어요. 테마 파일은 부분 재정의예요 — 바꾸고 싶은 색만 지정하면 돼요. 생략된 키는 내장 기본 테마 값으로 폴백해요.

# ~/.cagent/themes/my-theme.yaml
name: "My Custom Theme"

colors:
  # Backgrounds
  background: "#1a1a2e"
  background_alt: "#16213e"

  # Text colors
  text_bright: "#ffffff"
  text_primary: "#e8e8e8"
  text_secondary: "#b0b0b0"
  text_muted: "#707070"

  # Accent colors
  accent: "#4fc3f7"
  brand: "#1d96f3"

  # Status colors
  success: "#4caf50"
  error: "#f44336"
  warning: "#ff9800"
  info: "#00bcd4"

  # Optional: Customize syntax highlighting colors
  chroma:
    comment: "#6a9955"
    keyword: "#569cd6"
    literal_string: "#ce9178"

  # Optional: Customize markdown rendering colors
  markdown:
    heading: "#4fc3f7"
    link: "#569cd6"
    code: "#ce9178"

테마 적용 (Applying Themes)

사용자 구성(~/.config/cagent/config.yaml, 전체 참조는 User Settings):

settings:
  theme: my-theme # References ~/.cagent/themes/my-theme.yaml

시작 시: docker agent run에 --theme <name>을 전달해 그 세션의 테마를 미리 선택해요. 구성의 settings.theme을 재정의하지만 저장되지는 않아요. 잘못된 테마 이름은 시작 시 사용 가능한 옵션을 나열하는 오류를 출력해요. --exec 모드에서는 효과가 없어요. --theme auto는 세션의 자동 테마를 활성화해요.

런타임에: /settings를 열고 Appearance 탭에서 Theme를 선택한 다음 사용 가능한 테마에서 골라요. 선택은 ~/.config/cagent/config.yaml의 settings.theme 아래에 전역으로 저장되고 세션 간에 유지돼요.

팁 — 핫 리로드: 커스텀 테마는 파일에 변경을 저장하면 자동 재로드돼요 — 재시작 불필요. 실시간으로 색을 조정하기 쉽게 해줘요.

경고 — 부분 재정의: 모든 사용자 테마는 기본 테마 위에 적용돼요. 내장 테마(예: dracula)를 커스터마이즈하려면 GitHub의 내장 테마에서 전체 YAML을 ~/.cagent/themes/로 복사하고 사본을 편집하세요. 그렇지 않으면 생략된 값은 원래 테마 색이 아닌 기본 색을 사용해요.

도구 권한 (Tool Permissions)

에이전트가 도구를 호출하면 Docker Agent는 기본적으로 확인 대화상자를 보여줘요. 다음을 할 수 있어요:

한 번 승인 — 이 특정 호출 허용
항상 허용 — 세션에 대해 이 도구/명령 영구 승인
거부 — 도구 호출 거부

세분화된 권한: 권한 시스템은 패턴 기반 매칭을 지원해요. 특정 도구 명령을 "항상 허용"하면 그 정확한 패턴만 자동 승인되고, 같은 도구의 다른 명령은 여전히 확인이 필요해요. 이것은 파괴적인 작업에 대한 제어를 유지하면서 안전한 읽기 전용 작업을 자동 승인하게 해줘요.

팁 — YOLO 모드: --yolo 또는 /yolo 명령으로 모든 도구 호출을 자동 승인해요. 세션 중간에도 토글할 수 있어요. 별칭의 경우 별칭 생성 시 --yolo를 설정하세요: docker agent alias add fast myorg/coder --yolo.

알림 (Notifications)

TUI는 에이전트 경고, 오류, 다른 런타임 이벤트에 대한 일시적 알림 배너를 표시해요. 알림은 마우스가 위에 있지 않으면 짧은 지연 후 자동 닫혀요 — 마우스를 올리면 타이머가 멈춰 메시지를 읽을 시간을 줘요.

상호작용	동작
마우스 올리기	자동 닫기 일시 중지; 마우스가 떠날 때까지 알림 유지
클릭	알림 텍스트를 클립보드에 복사
× (닫기)	즉시 닫기; 마우스를 올리면 글리프가 빨개짐

알림 테두리 왼쪽 위의 힌트 텍스트는 사용 가능한 동작을 한눈에 보여줘요.