Kiln 문서Kiln 사용하기
Claude Code·Codex·Antigravity 함께 실행하기
워크스페이스에서 Claude Code, Codex, Antigravity 작업을 시작하고 상태를 확인하며, 서버 과부하로 중단된 Codex 턴을 Kiln이 다시 시도하게 합니다.
Kiln은 Claude Code, Codex, Google의 Antigravity CLI(agy)를 워크스페이스 패널 안에서 실행합니다. 요청을 쓰고 에이전트를 고르면, 터미널을 일일이 뒤질 필요 없이 사이드바에서 모든 작업의 상태를 확인할 수 있습니다.
시작하기 전에
에이전트는 외부 도구입니다. 사용할 에이전트마다 공식 CLI를 설치하고 로그인하세요. Kiln에는 어떤 에이전트의 구독도 포함되어 있지 않습니다.
- Claude Code와 Codex: CLI를 설치한 뒤 설정 → 계정에서 계정을 추가합니다. 계정을 참고하세요.
- Antigravity: Google 설치 프로그램으로
agy를 설치합니다. macOS에서는 설정 → 계정 → Antigravity에서, Windows에서는 터미널에서agy를 실행해 로그인합니다. Kiln은PATH,~/.local/bin,/opt/homebrew/bin,/usr/local/bin에서agy를 찾습니다.
Windows에서 Claude Code와 Codex는 네이티브 Windows 프로그램으로 실행되며, 홈 디렉터리는 각각 %USERPROFILE%\.codex와 %USERPROFILE%\.claude입니다.
작업 시작하기
새 작업을 선택하고 요청을 입력한 뒤 에이전트를 골라 시작합니다. 에이전트 선택기(Claude Code, Codex, Antigravity)는 요청 입력란 바로 아래에 고정되어 있습니다. 저장소 컨텍스트는 따로 스크롤되므로, 요약이 길어도 시작 버튼이 화면 밖으로 밀려나지 않습니다.
Antigravity는 다음 방법으로도 시작할 수 있습니다.
| 동작 | 하는 일 |
|---|---|
| 새 작업 → Antigravity | 현재 워크스페이스에서 agy를 시작합니다. |
| 새 작업 → 폴더에서 열기 → Antigravity | 먼저 폴더를 고르게 한 뒤 그 폴더에서 agy를 시작합니다. |
Antigravity로 새 작업 (명령 팔레트, ⌘K) |
Antigravity 작업을 시작합니다. |
요청 아래에서 Antigravity를 고르면 Kiln은 요청과 저장소 요약을 agy의 첫 프롬프트로 넘깁니다. antigravity 명령은 Antigravity 편집기를 여는 명령이므로 Kiln은 이를 에이전트로 다루지 않습니다.
보내지 않은 요청은 워크스페이스와 함께 저장되고, Kiln을 다시 열면 복원됩니다. 워크스페이스를 닫을 때는 요청을 버리기 전에 확인을 받습니다.
여러 저장소 함께 다루기
프론트엔드, 백엔드, 공유 라이브러리가 각각 다른 Git 저장소에 있다면 ~/dev/projects 같은 상위 폴더를 여세요. Kiln은 이 폴더를 에이전트의 작업 루트로 유지하고 찾아낸 저장소 구성을 요청에 함께 넣을 수 있으므로, 요청 하나로 모든 저장소를 다룰 수 있습니다.
Git이나 GitHub 도구에서 저장소를 살펴봐도 작업이 실행되는 디렉터리는 바뀌지 않습니다. Git 작업을 적용할 저장소는 해당 도구의 저장소 선택기에서 고릅니다. 워크스페이스와 작업과 Git과 GitHub를 참고하세요.
작업 상태 확인하기
사이드바의 각 작업 행에는 에이전트가 보고한 상태가 표시됩니다.
| 상태 | 의미 |
|---|---|
| 작업 중 | 에이전트가 작업하고 있습니다. |
| 입력 대기 | 에이전트가 내 입력을 기다립니다. |
| 완료 | 에이전트가 작업을 마쳤습니다. |
| 실패 | 에이전트가 실패를 보고했습니다. |
| 세션 열림 | 보고된 상태가 없습니다. Kiln은 짐작하지 않고 세션이 열려 있다고만 표시합니다. |
실행 중인 작업이 맨 위에 오고, 입력을 기다리는 요청, 이전에 실패한 작업 순으로 이어집니다. 작업을 클릭하면 해당 워크스페이스, 탭, 분할 화면으로 이동하며, 확대 때문에 가려진 패널도 다시 보입니다.
Kiln이 상태를 파악하는 방법
Kiln이 상태를 정확히 표시하려면 에이전트가 상태를 보고하거나 Kiln이 인식하는 실행 중 제목을 띄워야 합니다.
- Kiln은 Claude Code와 Codex의 터미널 제목에 나오는 활동 표시를 인식하므로, 따로 설정하지 않아도 실행 중 활동이 표시됩니다.
- Claude Code의
✳표시는 대화상자가 열려 있을 때도 나타나므로 완료로 보지 않습니다. - 명시적인 대기·실패 신호가 있으면 제목 표시보다 우선합니다.
- 유휴 상태의 터미널을 완료된 작업으로 보는 일은 없으며, 끝나지 않은 실행 명령 때문에 유휴 에이전트가 실행 중으로 표시되지도 않습니다.
스크립트나 다른 도구는 kiln activity running, waiting, done, failed로 상태를 보고할 수 있습니다. 활동 보고와 알림은 터미널을 참고하세요.
표시 색상
| 에이전트 | 표시 |
|---|---|
| Claude Code | 주황색 |
| Codex | 파란색 |
| Antigravity | 탭, 작업 목록, 사이드바에 Antigravity 마크 |
| 식별되지 않은 세션 | 중립색 |
표시는 사이드바, 탭, 패널 헤더에 나타납니다. 분할된 탭에서 상태의 우선순위가 같으면 포커스된 패널의 상태를 따릅니다. 경고는 언제나 우선합니다.
알림과 사용량 한도
알림 센터는 최근 알림을 보관하고 각 알림을 해당 세션과 연결해 둡니다. 알림을 읽으면 그 세션의 확인 필요 상태가 풀립니다. Windows에서는 에이전트 알림이 Windows 토스트로 뜹니다.
Antigravity가 할당량에 도달했다고 보고하면 Kiln은 초기화 시각과 함께 사용량 한도 알림을 띄웁니다. Claude Code와 Codex 패널은 처음 열 때 쓴 계정을 계속 씁니다. 계정이 사용량 한도에 도달하면 설정 → 계정에서 다른 계정으로 전환하고 새 패널을 여세요. 계정을 참고하세요.
Codex 용량 초과 복구
Kiln이 열려 있는 동안, Kiln이 관리하는 Codex 패널은 서버 과부하로 Codex가 중단한 턴을 다시 시도합니다. 재시도는 이 Codex 오류에서만 시작되며, 사용량 한도, 로그인 실패, 스트림 오류, 취소된 턴, 성공한 턴에는 관여하지 않습니다.
- 재시도 간격은 15, 30, 60, 120, 240초입니다. 패널에는 카운트다운과 자동 재시도 취소 버튼이 표시됩니다.
- 실패한 뒤 패널에 입력하면 대기 중인 재시도가 취소됩니다. 프롬프트를 일부만 입력해도 마찬가지입니다.
- 직접 새 요청을 보내면 재시도가 처음부터 다시 시작됩니다.
- 재시도할 때도 같은 계정과 모델을 씁니다.
Codex CLI가 아직 열려 있으면 Kiln은 같은 대화에 이어 가기 프롬프트를 한 번 보냅니다. CLI가 이미 종료되었다면 원래 계정과 작업 디렉터리로 같은 대화를 재개한 뒤 프롬프트를 보냅니다. 이 프롬프트는 이미 끝낸 동작을 반복하기 전에 현재 상태부터 확인하라고 Codex에 요청합니다. 원래 요청을 다시 보내지 않으며, 실패한 턴에서 생긴 변경도 되돌리지 않습니다.
재시도는 저장된 계정으로 연 Codex 패널 가운데 Kiln이 대화를 확인한 패널에만 적용됩니다. Kiln이 실행 중인 CLI를 지켜보기 전에 일어난 실패는 직접 처리해야 합니다.
Codex 백그라운드 서버 설정
Kiln이 여는 새 Codex 패널은 --no-daemon으로 실행되므로 Codex 자체의 공유 백그라운드 서버와 별개로 동작합니다. Codex 세션에 Background server has incompatible feature settings가 표시되면, 그 세션의 기능 플래그가 서버에 저장된 값과 다르다는 뜻입니다. 이때는 다음 중 하나를 고를 수 있습니다.
| 옵션 | 효과 |
|---|---|
| Run without daemon this time | 공유 Codex 서버를 재시작하지 않고 이 세션을 시작합니다. CLI의 codex --no-daemon과 같습니다. |
| Restart with these settings | 공유 설정을 바꿉니다. 다른 클라이언트에서 진행 중이거나 대기 중인 작업이 중단될 수 있으니 먼저 확인하세요. |