cost-xray로 AI 코딩 요청의 토큰 비용을 분석합니다

Claude Code나 Codex의 총사용량을 넘어 어떤 MCP 스키마와 도구 결과가 토큰 비용을 만드는지 찾으려는 개발자에게 cost-xray는 특정 상황에서 유용합니다. macOS·Linux에서 로컬 프록시를 신뢰하고 요청 내용을 저장할 수 있다면, 에이전트가 모델에 보내는 묶음을 소스별로 살펴볼 수 있습니다. 매달 쓴 총액만 궁금하다면 로컬 로그 분석부터 시작할 수 있습니다. 2026년 10월 10일 확인한 공식 저장소와 문서를 기준으로 설명합니다.

한눈에 보기

기능과 비교는 프로젝트 문서의 설명입니다. 직접 실행 여부와 측정 범위는 아래 ‘확인한 범위’에 정리했습니다. README

어떤 작업에 도움이 됩니까?

cost-xray는 Tigerless Labs가 공개한 AI 코딩 에이전트의 요청 분석 도구입니다. Claude Code와 Codex는 코드를 읽고 고치며 도구를 호출하는 에이전트이고, cost-xray는 이들이 모델 API와 주고받는 내용을 로컬에서 포착해 분석합니다. 기존 코딩 에이전트의 통신을 관찰하는 역할을 맡습니다. 프로젝트 소개

MCP는 에이전트가 외부 도구를 호출하는 연결 방식입니다. 모델이 도구를 고르려면 이름·설명·입력 형식을 알아야 하는데, 이 정의 묶음을 도구 스키마라고 부릅니다. 여러 MCP 서버를 연결하면 실제 호출 결과뿐 아니라 이러한 정의도 요청에 포함될 수 있습니다. cost-xray는 시스템 프롬프트, 스키마, 대화, 도구 결과 등을 나눠 어떤 소스가 요청 안의 공간을 차지하는지 표시한다고 설명합니다. 요청 창 점유와 MCP 분석

예를 들어 저장소 검색과 브라우저 도구를 연결한 세션에서 코드 파일만 읽었는데도 입력 토큰이 크다면, 사용하지 않은 서버의 스키마가 포함됐는지 살펴볼 수 있습니다. 반대로 스키마는 작고 파일 읽기 결과가 크다면, 연결한 도구를 줄이기보다 파일 범위와 출력 길이를 조정하는 방향을 검토합니다. 이는 README의 분석 항목을 적용한 작업 예시입니다. 원인을 찾은 뒤 연결과 출력 설정을 조정하는 일은 사용자가 맡습니다. 분석 화면의 해석

기존 도구와 무엇이 다릅니까?

README는 ccusage·codeburn 같은 로그 기반 도구가 모델·날짜·작업별 합계를 살피는 데 적합하다고 설명합니다. cost-xray의 구별점은 에이전트가 실행 뒤 남긴 기록 대신 실제 요청 시점의 내용을 관찰한다는 것입니다. 프로젝트는 시스템 프롬프트나 주입된 스키마처럼 일반 대화 기록에 남지 않는 부분까지 분석할 수 있다고 주장합니다. 비교 범위는 제작자가 설명한 데이터 수집 방식의 차이입니다. 공식 비교 설명

또한 비용과 컨텍스트 점유는 다른 판단 축입니다. 컨텍스트는 모델이 한 번에 참고하는 입력 공간입니다. 반복되는 스키마가 캐시로 저렴하게 처리돼도 요청 공간은 계속 차지할 수 있습니다. cost-xray는 새 입력, 캐시 읽기, 캐시 쓰기, 출력의 비용 구분과 소스별 점유를 함께 보여 준다고 설명합니다. 화면에서 비용이 작다고 해서 그 도구가 작업에 꼭 필요한지는 결정되지 않습니다. 캐시와 점유 구분

어떻게 사용합니까?

첫 작업은 MCP 도구를 여러 개 연결한 작은 세션에서 사용하지 않은 스키마를 찾는 것으로 잡을 수 있습니다. 입력은 비밀값이 없는 샘플 저장소와 기존 MCP 구성입니다. 에이전트에는 “README와 소스 파일 한 개를 읽고, 두 파일의 설명이 일치하는지 정리합니다. 파일은 수정하지 않습니다.”처럼 범위가 작은 요청을 줍니다. 이 문장은 재현 순서를 설명하기 위해 작성한 샘플 과제입니다.

설치 뒤 새 터미널에서 평소의 claude 또는 codex 명령을 실행합니다. 다른 터미널에서 cx로 텍스트 화면을 열고, 에이전트 → 프로젝트 → 세션 → 범주 → MCP 서버 → 도구 → 턴별 호출 → 실제 출력 순서로 내려갑니다. 설치 전에 이미 끝난 대화 기록을 가져오는 방식이 아니라, 새 셸에서 시작한 실행부터 포착하는 방식입니다. 공식 사용 순서

이때 서버별 스키마 점유와 실제 호출을 함께 봅니다. 스키마는 반복해서 보이는데 호출이 없다면 해당 작업에서 연결을 줄일 후보로 기록합니다. 큰 tool_result가 반복된다면 파일 읽기나 셸 출력이 요청에 얼마나 남는지 살펴봅니다. 사용하지 않은 도구라도 다른 작업에 필요할 수 있으므로 한 세션의 결과만으로 전체 설정을 제거하기보다 같은 범위의 작업을 비교합니다. README도 화면의 패턴을 최종 판정이 아닌 조사 출발점으로 설명합니다. 화면 해석 가이드

기대 결과는 “어느 소스를 다음에 조정할지”를 정하는 메모입니다. 도구가 제공하는 것은 요청의 점유와 비용 귀속이고, 조정 뒤 코드 품질·테스트 결과·필요한 도구가 유지되는지 확인하는 일은 사용자가 맡습니다. 이 글에는 실제 화면에서 관찰한 수치나 비용 절감 결과를 싣지 않습니다.

설치와 이용 조건

README의 지원 대상은 macOS·Linux와 이미 사용할 수 있는 Claude Code 또는 Codex입니다. Windows 네이티브 지원은 목록에 없으며, 설치 문서의 WSL 수동 모드 언급을 Windows 전체 지원으로 확대해 해석하지 않습니다. Python과 mitmproxy 기반이고, 설치기는 필요한 가상환경을 준비하며 시스템 Python이 없거나 너무 오래되면 uv를 통해 Python을 받아옵니다. 설치 참고 문서

공식 설치 명령은 다음과 같습니다. 원격 master의 스크립트를 내려받아 셸로 실행하므로 실행 시점의 브랜치 내용에 따라 설치되는 코드가 달라집니다. 실행 전 스크립트와 아래 변경 범위를 검토할 수 있습니다. 공식 설치 절차

curl -fsSL https://raw.githubusercontent.com/tigerless-labs/cost-xray/master/install.sh | bash

설치기는 Claude Code·Codex·둘 다 중 포착할 대상을 묻습니다. 선택 질문을 생략할 때는 COST_XRAY_AGENTS 환경 변수에 claude, codex, all 중 하나를 지정합니다. Codex 선택은 해당 명령이 신뢰할 로컬 CA, 즉 프록시 인증서를 검증하는 인증기관을 준비하는 데 동의하는 절차라고 안내합니다. OS 전체 신뢰 저장소에는 추가하지 않는다고 설명합니다. 대상 선택과 CA 동의

Linux에서는 systemd 사용자 서비스와 부팅 시 시작을 위한 linger를, macOS에서는 launchd 로그인 시작 서비스를 구성합니다. systemd나 launchd가 없는 일부 컨테이너·WSL에서는 재부팅 뒤 유지되지 않는 수동 모드로 자동 전환된다고 설명합니다. 셸 설정에는 claude()·codex() 래퍼와 cx를 추가합니다. 따라서 앱 코드를 직접 수정하는 설치는 아니지만, 기존 에이전트 명령의 통신 경로와 백그라운드 실행 환경을 바꿉니다. 설치가 만드는 파일과 서비스

Claude Code는 기본 API 주소를 로컬 역방향 프록시로 바꾸며 별도 CA가 필요하지 않습니다. Codex는 정방향 프록시와 명령에 한정된 CA를 사용합니다. 기본 포트는 각각 8788·8789지만, 충돌하면 다른 빈 포트를 선택하므로 cx status의 실제 값을 확인합니다. GUI 앱은 셸 래퍼를 읽지 않아 앱 자체의 접속 설정이 별도로 요구됩니다. 통신 방식과 포트

cx status
cx stop
cx start
cx uninstall

cx stop은 포착을 중단해 에이전트를 직접 연결로 돌리고, cx start는 재개합니다. 한 번만 우회하려면 CX_OFF=1 claude 또는 CX_OFF=1 codex를 사용할 수 있습니다. cx uninstall은 서비스와 셸 래퍼를 제거하지만 포착된 데이터는 남깁니다. 저장된 세션까지 비우는 일은 별도로 처리합니다. 중단·우회·제거

비용과 라이선스

프로젝트는 MIT 라이선스로 공개돼 있습니다. 저작권·라이선스 고지를 복사본이나 주요 부분에 유지하는 조건으로 이용·수정·배포·상업적 이용을 허용하며 보증 없이 제공합니다. 2026년 10월 10일 확인한 문서에서 도구 자체의 구독료나 별도 유료 기능은 발견되지 않았습니다. 기존 Claude Code·Codex의 이용 요금과 모델/API 비용은 사용하는 계정·제공자 조건을 따릅니다. MIT 라이선스, 이용 요구사항

소스별 달러 표시는 제공자 사용량과 가격표를 바탕으로 계산합니다. 구독 계정에서 보이는 분석 금액을 곧바로 그 계정의 추가 청구액이나 절감 가능한 현금으로 바꾸지는 않습니다. 아키텍처 문서는 LiteLLM 가격표를 하루 단위로 캐시해 가져오고, 오프라인에서는 번들 사본을 사용한다고 설명합니다. 가격표의 최신성·모델 지원·캐시 단가가 계산의 조건입니다. 가격 자료의 처리

도구는 새 유료 제공자를 기본으로 선택해 가입시키는 설치를 안내하지 않습니다. 다만 로컬 분석이라는 설명을 인터넷 통신이 전혀 없다는 뜻으로 읽지는 않습니다. 설치 자료 다운로드와 기존 모델 호출 외에 가격표 갱신이 있고, 인증된 Claude 환경에서는 토큰 보정에 Anthropic의 count_tokens 엔드포인트를 사용한다고 설명합니다. 미인증일 때는 고정 비율로 보정합니다. 해당 호출의 실제 발생량과 계정별 영향은 미검증입니다. 보정 방법, 분석 파이프라인

한계와 유지보수

Claude의 소스별 토큰 수는 tiktoken으로 추정한 뒤 특정 항목을 보정하고 제공자 사용량 합계에 맞춰 배분합니다. README가 합계의 정확성을 강조하더라도 각 MCP 서버·도구에 배분된 값은 추정입니다. 전체 항목을 count_tokens 차분으로 계산하는 선택형 정확 모드는 README에서 예정 기능으로 적혀 있어 현재 사용할 수 있는 기능으로 소개하지 않습니다. 토큰 정확성 설명

가격 계산에도 별도 제약이 있습니다. 2026년 10월 10일 확인한 이슈 #19는 Open 상태이고 연결된 브랜치·PR이 표시되지 않습니다. 제보 내용은 LiteLLM 항목에 캐시 가격 필드가 없을 때 공급자 구분 없이 Anthropic식 배수를 대입한다는 것입니다. 캐시 필드가 있는 모든 모델이 틀렸다는 주장과는 다릅니다. 새 모델이나 드문 모델의 계산 금액을 판단할 때 제공자 가격과 대조할 이유가 됩니다.

한국어 데이터와 관련해서는 9월 5일 제보된 이슈 #14가 Open으로 남아 있습니다. 제보 내용은 파일 입출력 약 30곳에 encoding="utf-8"이 빠져 있어, 기본 인코딩이 로케일을 따르는 Windows에서 한글·이모지가 든 세션 이름·경로·도구 설명이 손상될 수 있다는 것입니다. 이후 9월 29일 커밋 기록에는 인코딩 수정 PR #11·#12·#13 병합이 있고, 같은 날 병합된 PR #21은 앞선 수정에서 빠진 입출력을 보완하며 CJK·악센트·이모지를 ASCII 로케일에서 왕복시키는 테스트를 추가했다고 설명합니다. 다만 PR #21은 이슈 #14를 언급하거나 닫지 않았으므로, 제보된 모든 위치가 고쳐졌는지는 확인하지 못했습니다. 이 수정은 Windows 지원 선언과도 구분합니다.

보관 범위도 도입 조건입니다. 문서는 인증 헤더·API 키·쿠키·비밀값처럼 보이는 본문 필드를 디스크 기록 전에 가리고, 로컬 주소에만 바인딩하며 텔레메트리를 보내지 않는다고 설명합니다. 그래도 일반 프롬프트와 코드·도구 출력은 남을 수 있습니다. 요청 내용을 저장할 수 없는 회사 환경에는 맞지 않습니다. 중복 블록을 한 번씩 저장하는 구조는 저장량을 줄이며, 저장된 본문의 민감성은 별도로 검토합니다. 저장·가림 구조, 개인정보 관련 설명

유지보수 신호로는 커밋 기록의 2026년 9월 29일 병합까지 확인했습니다. 10월 10일 조회 시점의 master 최신 커밋은 PR #21 병합 커밋 069733f였고, 별도 릴리스 버전은 없습니다. 설치 명령이 움직이는 master를 사용하므로 이 글의 확인 시점 이후 내용이 달라질 수 있습니다. 단일 메인테이너인지, 장기 지원을 보장하는 조직 체계인지는 확인 범위 밖입니다.

확인한 범위

문서 확인: 2026년 10월 10일 저장소, README, 설치·아키텍처 문서, MIT 라이선스, 커밋 기록을 대조했습니다. 기준은 확인일의 master 최신 커밋인 9월 29일 069733f(PR #21 병합)입니다. 그 직전 문서 변경은 9월 1일 5d69deb이고, 그 사이에 들어온 변경은 UTF-8 인코딩 수정 PR #11·#12·#13·#21입니다. 이슈 #14·#19의 열린 상태도 원문으로 확인했습니다. 커밋 기록, 후속 병합 설명

직접 실행: 직접 실행하지 않았습니다. 설치, CA 생성, 실세션 포착, 가격 대조와 한국어 화면 표시는 시험 범위에 포함되지 않습니다. 앞의 사용 절차는 문서에 근거한 도입 예시입니다.

도입 판단

특정 상황에 유용합니다. macOS·Linux에서 여러 MCP 연결이나 큰 도구 출력의 토큰 점유를 조사하고 싶고, 요청 내용을 로컬에 남기는 조건을 받아들일 때 검토할 만합니다. 월별·세션별 합계만 보면 되는 경우에는 기존 사용량 표시나 로그 분석 도구로 시작할 수 있습니다.

다음 행동은 민감하지 않은 샘플 저장소의 작은 읽기 작업을 포착해, 실제 저장되는 내용과 스키마·호출·출력 구분을 먼저 확인하는 것입니다. 원인 후보를 찾은 뒤 연결 설정을 조정하고 작업 결과도 함께 비교합니다. Windows 네이티브 사용자, 프록시·CA 경유가 허용되지 않는 환경, 소스별 금액을 정확한 정산 근거로 삼으려는 경우에는 현재 확인 범위로 도입을 권하기 어렵습니다. 지원 조건과 분석 범위

참고한 자료

모든 자료의 확인일은 2026년 10월 10일입니다. 공개 1차 출처의 기능 설명과 제보를 대조했습니다. 기능은 프로젝트 측 설명으로, 이슈는 제보와 상태를 구분해 전달합니다.

• 공식 저장소: 프로젝트와 지원 에이전트를 확인했습니다.
• README: 분석 범위·사용 예·토큰 추정 설명을 확인했습니다.
• 설치 참고 문서: 명령·서비스·권한·중단·제거 절차를 확인했습니다.
• 아키텍처 문서: 저장·가림·보정·가격표 처리 구조를 확인했습니다.
• 커밋 기록: 기준 커밋과 후속 병합 날짜를 확인했습니다.
• UTF-8 이슈 #14: 한국어·비ASCII 데이터 관련 제보와 열린 상태를 확인했습니다.
• UTF-8 후속 수정 PR #21: 남은 입출력 수정과 회귀 테스트 설명, 병합 상태를 확인했습니다.
• 캐시 가격 이슈 #19: 가격 필드가 빠진 모델의 대체 계산 제보를 확인했습니다.
• MIT 라이선스: 상업적 이용과 고지 유지 조건을 확인했습니다.