클로드 코드 상태 표시줄에 작업 진행률과 남은 시간 표시하기
클로드 코드 상태 표시줄에 작업 진행률과 남은 시간을 띄우는 플러그인을 만들고, 실제 세션 127개로 정확도를 검증한 과정을 정리했습니다.
클로드 코드 상태 표시줄은 세션 데이터를 stdin으로 받아 원하는 정보를 화면 아래쪽에 그리는 기능입니다. 컨텍스트 사용량, 비용, git 브랜치를 띄우는 설정은 널리 쓰입니다. 그런데 정작 궁금한 정보 하나가 빠져 있습니다. 지금 돌아가는 작업이 언제 끝나는지입니다.
파일을 복사할 때는 남은 시간이 보입니다. 늘어나기도 하고 줄어들기도 하지만 기다릴지 다른 일을 할지 정하는 데는 충분합니다. 클로드 코드에서 큰 리팩터링을 시킬 때 그 정보가 없으면 화면만 보고 있게 됩니다. 이 궁금증에서 시작해 상태 표시줄에 진행률과 남은 시간을 붙였고, 그 과정에서 확인한 것들을 정리했습니다.
클로드 코드 상태 표시줄이 받는 데이터와 갱신 방식
상태 표시줄에 무엇을 그릴 수 있는지는 클로드 코드가 무엇을 넘겨주는지에 달려 있습니다. 공식 문서는 stdin으로 전달되는 JSON 필드를 전부 공개합니다. 2026년 8월 기준으로 쓸 만한 값은 다음과 같습니다.
model.display_name: 현재 모델 이름context_window.used_percentage: 미리 계산된 컨텍스트 사용 비율cost.total_duration_ms: 세션 시작 이후의 총 경과 시간transcript_path: 대화 기록 파일의 경로session_id: 세션마다 고유한 식별자
이 가운데 마지막 두 개가 이번 작업의 출발점이 됐습니다. transcript_path가 가리키는 JSONL 파일에는 어떤 도구를 언제 호출했고 언제 결과가 돌아왔는지가 한 줄씩 남습니다. 남은 시간을 계산할 재료가 이미 로컬에 다 있다는 뜻입니다.
갱신 방식도 문서에 적혀 있습니다. 스크립트는 새 어시스턴트 메시지가 나온 뒤에 실행되고, 업데이트는 300밀리초에서 디바운스됩니다. 여기에 중요한 제약이 하나 붙습니다.
스크립트가 여전히 실행 중인 동안 새 업데이트가 트리거되면 진행 중인 실행이 취소됩니다.
문서의 문제 해결 항목에는 느린 스크립트가 완료될 때까지 상태 표시줄 갱신을 막는다는 설명도 함께 있습니다. 상태 표시줄은 로컬에서 실행되며 API 토큰을 쓰지 않습니다. 대신 스크립트가 느리면 화면이 그만큼 늦게 갱신됩니다. 이 제약은 뒤에서 실제 숫자로 이어집니다.
경과 시간을 그대로 쓰면 예측이 성립하지 않습니다
처음에는 단순하게 접근했습니다. 과거 기록에서 같은 스킬을 실행한 구간을 찾아 걸린 시간을 평균 내면 될 것 같았습니다. 세션 기록 전체를 훑어 측정한 결과는 이랬습니다.
| 스킬 | 실행 횟수 | 최소 | 최대 |
|---|---|---|---|
| 글쓰기 스킬 | 15회 | 1.2분 | 81.5분 |
| 문체 검수 스킬 | 10회 | 2.1분 | 72.6분 |
같은 작업인데 수십 배씩 벌어집니다. 스킬 전체를 놓고 보면 최대 166배까지 차이가 났습니다. 이런 분포로는 평균을 내도 쓸 수 없습니다.
원인은 다른 숫자에서 드러났습니다. 사용자에게 질문을 던지는 도구는 중앙값이 54초인데 평균은 1531초였습니다. 대부분은 1분 안에 답이 오지만 가끔 몇 시간씩 자리를 비우고, 그 시간이 평균을 끌어올립니다. 클로드가 일한 시간이 아니라 사람이 답을 고민하거나 자리를 비운 시간이 통째로 들어가 있었습니다.
90초가 넘는 공백을 사람이 자리를 비운 시간으로 보고 제외했습니다.
| 스킬 | 도구 호출 수 | 실작업 시간 | 호출당 소요 |
|---|---|---|---|
| 글쓰기 스킬 | 26회 | 6.1분 | 13.4초 |
| 문체 검수 스킬 | 15회 | 4.0분 | 13.0초 |
| 영상 편집 스킬 | 59회 | 10.1분 | 11.1초 |
편차가 수십 배에서 2배 남짓으로 줄었습니다. 호출당 소요 시간이 11초에서 23초 사이에 모입니다. 여기서 계산 방식이 정해졌습니다.
진행률 = 지금까지 도구 호출 수 / 예상 총 호출 수
남은 시간 = (예상 총 호출 수 - 지금까지) × 호출당 소요 시간남은 분량에 단위당 걸리는 시간을 곱하는 방식입니다.
진행률이 100%에서 멈추지 않게 만드는 조건부 분포
여기서 문제가 하나 더 나옵니다. 예상 총 호출 수를 과거 중앙값으로 고정하면, 작업이 그 수를 넘어가는 순간 진행률이 100%에 붙어 움직이지 않습니다. 실제로는 아직 한참 남았는데 화면은 다 끝났다고 말하는 상태가 됩니다.
해결 방법은 질문을 바꾸는 것이었습니다. 이 작업이 보통 몇 번에 끝나는지를 묻는 대신, 이미 20번 호출한 경우들이 몇 번에서 끝났는지를 과거 표본에서 다시 뽑습니다. 조건부 분포입니다. 20번을 넘긴 사례들만 놓고 중앙값을 구하면 분모가 자연히 커지고, 오래 걸리는 작업은 예상 시간도 함께 늘어납니다.
파일 복사는 전체 크기를 알지만 이 도구는 모릅니다. 총 작업량을 모른 채 진행률을 표시해야 한다는 점이 가장 큰 제약입니다.
작업이 끝나는 시점을 잡는 것도 따로 처리가 필요했습니다. 처음에는 다음 사용자 입력이 들어올 때 작업을 닫도록 만들었는데, 그러면 응답이 끝나고 입력을 기다리는 동안 진행률이 94% 같은 어중간한 값에 멈춰 있었습니다. 대화 기록에는 stop_reason이 end_turn으로 남는 순간이 있습니다. 이 값을 종료 신호로 쓰니 작업이 끝나는 즉시 100%로 정리됐습니다.
실제 세션 127개로 측정한 정확도
직접 만든 도구는 잘 맞는 것처럼 보이기 쉽습니다. 그래서 검증 방법을 먼저 정했습니다. 세션 127개를 시간순으로 나눠 앞 70%로만 학습하고, 뒤 30%는 실시간인 것처럼 재생하면서 중간중간 예측을 내게 했습니다. 각 시점에서 추정기가 볼 수 있는 정보는 그 순간까지의 기록뿐입니다. 작업 252개, 측정 시점 756개가 나왔습니다.
| 지표 | 결과 | 고정값 방식 |
|---|---|---|
| 중앙 오차 | 56% | 100% |
| 2배 이내 | 57% | 32% |
| 3배 이내 | 78% | 48% |
| 표시 범위가 실제를 포함 | 69% | 없음 |
중앙 오차 56%는 "5분 남음"이 실제로는 3분에서 11분 사이라는 뜻입니다. 기다릴지 다른 일을 할지 정하는 데는 쓸 수 있지만 일정을 잡을 숫자는 아닙니다.
이 수치는 2026년 8월 7일에 측정한 값입니다. 세션 기록이 쌓이면 학습과 검증에 쓰이는 데이터가 함께 늘어나므로, 같은 도구를 다시 돌려도 몇 퍼센트포인트씩 달라집니다.
오차가 어디서 오는지도 분해했습니다. 총 호출 수를 실제 값으로 바꿔 넣으면 오차가 26%로 떨어지고, 호출당 소요 시간을 실제 값으로 바꾸면 오히려 나빠집니다. 예측이 어려운 쪽은 속도가 아니라 작업의 총량이었습니다. 요청 문장의 길이로 총량을 짐작할 수 있을지 측정했지만 상관계수가 0.12로 거의 관계가 없었고, 경과 시간에 비례시키는 방식은 오차 65%로 더 나빴습니다.
측정 결과 가운데 예상과 달랐던 것이 하나 있습니다. 같은 스킬을 자주 쓰면 예측이 정확해진다고 생각하기 쉽지만, 표본이 쌓이는 것과 정확도는 생각만큼 붙어 있지 않았습니다.
| 분류 | 표본 | 중앙 호출 수 | 변동계수 |
|---|---|---|---|
| 일반 실행 작업 | 200회 | 7회 | 1.24 |
| 스킬 A | 11회 | 26회 | 0.60 |
| 스킬 B | 6회 | 60회 | 0.20 |
표본이 6개뿐인 스킬 B가 표본 200개인 일반 실행 작업보다 훨씬 일관적입니다. 실제 오차도 스킬 구간이 52%, 일반 작업이 56%로 표본이 적은 쪽이 낫습니다. 정확도를 정하는 것은 얼마나 자주 썼는지가 아니라 그 작업이 매번 비슷한 분량으로 끝나는지였습니다.
그래서 표시 방식을 근거 수준에 맞췄습니다. 표본이 충분하면 단일 숫자를, 얇으면 범위와 함께 표본이 부족하다는 사실을 적습니다.
⏳ ░░░░░░░░░░ 작업 시간 계산 중 (경과 25초)
⏳ 코드 작업 ███░░░░░░░ 30% 남은 시간 ~2분 (툴콜 3/10, 경과 50초)
⏳ 문서 작성 ███░░░░░░░ ~33% 남은 시간 3분~13분 (표본 부족) (툴콜 16/48)
✓ 코드 작업 ██████████ 100% 완료 (툴콜 93, 27분)남은 시간에서 초 단위를 뺀 것도 같은 이유입니다. 오차가 56%인 값에 "2분 40초"라고 적으면 없는 정밀도를 주장하게 됩니다.
0.3초 갱신 주기와 기록 전체를 읽는 비용
성능은 처음부터 다룰 생각이 없었는데 측정 과정에서 드러났습니다. 기존에 쓰던 상태 표시줄 플러그인이 86MB짜리 세션 기록을 읽는 데 0.3초에서 1.1초를 쓰고 있었습니다. 파일이 운영체제 캐시에 올라와 있는지에 따라 편차가 크지만, 갱신 주기인 300밀리초를 넘는 경우가 잦습니다. 앞서 인용한 문서 내용대로 실행 중이던 스크립트가 취소되는 상황이 반복됩니다.
원인은 매번 기록 전체를 처음부터 읽는 방식이었습니다. 지금 필요한 정보는 현재 작업 구간뿐인데 몇 달 치를 다 훑고 있었습니다. 두 가지로 나눠 처리했습니다.
- 처음 실행: 파일 끝에서 거꾸로 올라가며 현재 작업이 시작된 지점을 찾습니다. 그 앞은 읽지 않습니다.
- 이후 갱신: 지난번에 읽은 바이트 위치부터 새로 붙은 부분만 읽습니다.
| 상황 | 기록 전체를 읽는 방식 | 필요한 부분만 읽는 방식 |
|---|---|---|
| 90MB 세션, 첫 실행 | 0.3~1.1초 | 3ms |
| 갱신할 때마다 | 0.3~1.1초 | 0~1ms |
거꾸로 읽을 때 한 가지 요령이 필요했습니다. 도구 결과와 실제 사용자 입력은 기록에서 둘 다 user 타입으로 남습니다. 도구 결과 쪽이 훨씬 많고 용량도 크기 때문에, JSON을 파싱하기 전에 tool_result 문자열이 들어 있는 줄을 먼저 걸러내면 거꾸로 훑는 비용이 크게 줄어듭니다. 이 처리를 넣기 전에는 작업 하나가 16MB를 넘는 세션에서 시작 지점을 못 찾고 포기하는 경우가 있었습니다.
읽는 방식을 바꿨으니 결과가 같은지도 확인해야 했습니다. 가장 큰 기록 6개와 가장 작은 4개를 골라 전체를 읽은 결과와 대조했고 10건 모두 일치했습니다.
설치 방법과 남은 한계
만든 플러그인은 claude-code-eta라는 이름으로 공개해 뒀습니다. 클로드 코드 안에서 세 단계로 설치하며, 한 번에 하나씩 넣어야 합니다.
먼저 /plugin marketplace add를 실행합니다. 소스를 묻는 칸에는 저장소 경로만 넣습니다.
osomahong/claude-code-eta
다음으로 설치하고 설정을 실행합니다.
/plugin install claude-code-eta
/claude-code-eta:setup
세 줄을 첫 입력창에 한꺼번에 붙여 넣으면 Invalid marketplace source format 오류가 납니다. 소스 칸은 저장소 경로만 받습니다.
설치 과정에서 기존 상태 표시줄 설정을 백업 파일로 옮겨 두므로 되돌리기도 한 줄입니다. 통계는 로컬에 쌓이고 밖으로 나가는 통신은 없습니다. 저장하는 값은 도구 이름, 타임스탬프, 호출 횟수뿐이고 대화 내용은 넣지 않습니다.
한계도 그대로 적어 둡니다. 작업 구간을 넷으로 나누면 초반과 중반은 오차가 49%에서 53%인데 마지막 4분의 1이 75%로 가장 나쁩니다. 곧 끝나는 상황을 미리 알아채지 못해 남은 시간을 실제보다 길게 잡습니다. 총 작업량을 모른 채 추정한다는 제약에서 나오는 문제라 지금 구조로는 더 줄이기 어려워 보입니다.
비슷한 시도가 이미 있는지도 확인했습니다. 할 일 목록의 완료 간격으로 남은 시간을 계산하는 플러그인이 있는데, 할 일 목록을 쓰지 않는 세션에서는 표시가 나오지 않습니다. 도구 호출을 직접 세면 그 제약이 없습니다. 상태 표시줄에 완료 예상 시간을 넣어 달라는 요청이 클로드 코드 저장소에 올라온 적도 있지만 계획 없음으로 닫혔습니다. 당분간은 각자 만들어 쓰는 영역으로 보입니다.
3줄 요약:
- 클로드 코드 상태 표시줄은 세션 데이터를 stdin으로 받으며, 대화 기록 경로가 함께 넘어와 작업 시간을 계산할 재료가 로컬에 이미 있습니다.
- 남은 시간을 재려면 사용자가 자리를 비운 시간을 먼저 빼야 하고, 총 작업량은 조건부 분포로 다시 뽑아야 진행률이 100%에서 멈추지 않습니다.
- 세션 127개로 검증한 중앙 오차는 56%이므로, 기다릴지 정하는 용도로 쓰고 일정을 잡는 숫자로 쓰지 않는 편이 맞습니다.
Sources
이 글이 도움이 되셨다면 공유해 주세요
메신저로 바로 보내거나 링크를 복사할 수 있습니다.
디지털마케터 뉴스레터
GA4, SEO, AI 마케팅 실무 인사이트를 월 1~2회 이메일로 보내드립니다.
다음으로 읽어볼 글
Muse Code는 메타가 2026년 8월 5일 베타로 공개한 터미널 기반 AI 코딩 에이전트입니다. 상주형 백그라운드 에이전트, 병렬 하위 에이전트, 이벤트 로그 복구 같은 핵심 기능과 Muse Spark 1.2 벤치마크, 요금 구조를 클로드 코드와 나란히 놓고 정리했습니다.
2026. 8. 6.
Solar Open 2는 업스테이지가 2026년 7월 22일 가중치까지 공개한 250B 규모의 오픈웨이트 언어 모델입니다. 공식 벤치마크에서 이긴 항목과 뒤진 항목, 클로드 코드에 연결하는 공식 방법, 8월 6일 공개된 상용 모델 Solar Pro 4와의 역할 차이를 정리했습니다.
2026. 8. 6.
Qwen3.8-Max는 알리바바 Qwen 팀이 2026년 8월 3일 공개한 2조 4천억 파라미터 규모의 MoE 모델입니다. 공개 자료에 적힌 사양과 가격, 16일 자율 코딩을 포함한 장기 작업 실험 결과, 벤치마크를 읽을 때 주의할 점을 정리했습니다.
2026. 8. 4.
할루시네이션은 AI가 사실이 아닌 내용을 사실인 것처럼 만들어 내는 현상입니다. 법정에서 벌어진 실제 사건과 모델별 환각률 공개 데이터, 그리고 최신 상위 모델이 오히려 높게 측정되는 이유를 정리했습니다.
2026. 8. 3.클로드 코드 작업의 소요 시간을 과거 기록에서 학습할 때, 경과 시간을 그대로 쓰면 예측이 성립하지 않는 가장 큰 이유는 무엇일까요?
