AI 코딩 에이전트를 위한 통합 비용 추적기를 구축한 방법

AI 코딩 에이전트(AI coding agents)는 놀랍습니다 — 청구서가 도착하기 전까지는 말이죠. 그리고 그 청구서는 세 곳에서 동시에 도착할 것입니다: 한 디렉토리에서는 Claude Code, 다른 곳에서는 Cursor, 세 번째 곳에서는 Codex가 말이죠. 각 에이전트는 서로 다른 필드 이름과 서로 다른 가격 모델을 가진 각자의 JSONL 형식으로 사용량을 기록합니다.

그래서 저는 이 세 가지를 모두 읽고, 정규화(normalize)하여, 모델별, 일별, 에이전트별로 **하나의 비용 보고서(one cost report)**를 생성하는 작은 로컬 도구를 만들었습니다. 또한 80%에서 경고를 주고 100%에서 플래그를 표시하는 예산 가드레일(budget guardrails) 기능도 포함했습니다. 제가 무엇을 했는지 소개합니다.

어려운 부분: 세 가지의 서로 다른 로그 형식

각 에이전트는 사용량을 다르게 기록합니다:

// Claude Code — message 아래에 usage가 중첩되어 있으며, cache 필드가 포함됨
{"type":"assistant","message":{"model":"claude-sonnet-4-20250514",
  "usage":{"input_tokens":523,"output_tokens":187,"cache_read_input_tokens":1200}},
...

파서(parser)는 형식을 가정할 수 없습니다. 세 개의 수동 작성된 파서를 만드는 대신, 저는 객체 트리(object tree)를 탐색하여 모든 usage 객체를 찾아내고 폴백(fallback) 메커니즘과 함께 토큰을 추출하는 하나의 **재귀적 추출기(recursive extractor)**를 작성했습니다:

function extractUsage(obj, out, parentTs) {
  if (!obj || typeof obj !== 'object') return;
  if (obj.usage) {
...

이 방식은 하나의 코드 경로로 세 가지 형식(및 향후 추가될 형식)을 모두 처리합니다.

가격 엔진: 23개의 제공업체, 캐시 할인

진정한 통찰은 이것입니다: 유용하기 위해서 모델별로 완벽한 정확도가 필요한 것은 아닙니다 — 폭주하는 지출을 포착할 수 있을 만큼의 충분히 좋은(good enough) 수준이면 됩니다. 저는 23개 제공업체(Anthropic, OpenAI, DeepSeek, Google 등)의 가격 테이블을 재사용하며, 정확한 이름이나 접두사(prefix)로 매칭하고, 알 수 없는 모델의 경우 제공업체 이름 추측을 통해 폴백합니다:

function estimateCost({ model, inputTokens, outputTokens, cachedReadTokens = 0 }) {
  const price = lookupModel(model);          // $/1K tokens
  const cached = Number(cachedReadTokens) || 0;
...

알 수 없는 모델은 추정 요율(보고서에 플래그 표시됨)을 적용받으므로, 총액에서 아무것도 조용히 사라지지 않습니다.

예산 가드레일

핵심 기능은 보고서가 아니라 바로 **한도 (limit)**입니다. 월간 예산을 설정하면, 도구가 현재 상태를 다음과 같이 알려줍니다:

• < 50% — 정상 (OK)
• ≥ 80% — 경고 (WARN) (현재 속도라면 예산을 초과하게 됩니다)
• ≥ 100% — 초과 (OVERRUN)

Guardrail: $0.0698 / $50 (0%) → OK

두 가지 형태: CLI + MCP

개발자들은 터미널(terminal)에서 작업하지만, 에이전트(agent)들은 MCP 생태계에서 활동합니다. 따라서 이 도구는 두 가지 형태로 제공됩니다:

• CLI: agentcost scan ~/.claude/projects 50 → 터미널 보고서 생성
• MCP 서버 (MCP server): scan_cost, get_budget, set_budget 도구를 노출합니다. 이를 통해 코딩 에이전트가 스스로 "이번 달에 얼마를 썼지?"라는 질문에 답할 수 있게 합니다.

배운 점

1. 필드 이름의 불일치 (Field-name drift)가 진짜 비용이다 — input_tokens vs prompt_tokens vs inputTokens. 하나의 재귀적 추출기 (recursive extractor)가 세 개의 파서 (parser)보다 낫습니다.
2. 캐시 회계 (Cache accounting)가 중요하다 — Claude의 캐시된 읽기 (cached reads)는 약 10배 더 저렴합니다. 이를 무시하면 긴 세션에서 비용이 심하게 과다 계상됩니다.
3. 침묵보다는 추정치가 낫다 — "$0"로 표시되는 알 수 없는 모델은 사용자가 도구를 무시하게 만듭니다. 대신 추정치 (estimated)로 플래그를 표시하세요.
4. 로컬 우선 (Local-first)은 하나의 기능이다 — "데이터가 기기를 떠나지 않는다"는 것은 사용자들이 실제로 신경 쓰는 개인정보 보호(privacy) 이야기이며, 특히 비용 데이터의 경우 더욱 그렇습니다.

상태

이 프로젝트는 초기 릴리스 단계(v0.1, 테스트 22개 중 22개 통과)이며 npm에서 사용할 수 있습니다: agentcost-cli. 이것은 SellerTools 제품군의 첫 번째 오픈 소스 도구입니다. Claude Code / Cursor / Codex 헤비 유저분들의 피드백을 기다리고 있습니다. 여러분의 워크플로우에서 무엇이 부족한가요? 프로젝트별 예산? 팀별 집계? 이상 징후 알림? 댓글로 알려주세요.