Agent Profiler: 세션 시간이 어디로 가는지 보여 주는 Claude Code 프로파일러

Agent Profiler는 YeonwooSung이 만든 Claude Code 프로파일러로, my-claude-code-mods 모음의 일부입니다. 답해 주는 질문은 하나입니다. 세션이 느리게 느껴질 때 시간은 어디로 갔을까요? 각 턴의 시간을 모델 응답 대기, 도구 실행, 차단형 서브에이전트, 엔진 오버헤드로 나누고 결과를 세 곳에 보여 줍니다.

• 상태 표시줄: Claude가 작업하는 동안 실시간으로 갱신됩니다. 예: model 100% · tools 0% · ▶ model claude-haiku-5-5 12.5s.
• /profile: 세션 전체의 텍스트 보고서이며, /profile turn은 마지막 턴만 보여 줍니다. 시간 범주, 첫 토큰까지의 시간, 토큰 수, 느린 도구, 반복해서 읽은 파일, 서브에이전트, 짧은 발견 사항 목록이 들어 있습니다.
• /profile-pane: 진행 중인 요청과 도구를 보여 주는 실시간 패널입니다. /profile-export는 세션을 OTLP JSON으로 기록합니다.

이 모드는 주장에 신중합니다. "추론 시간"은 보고하지 않습니다. 모든 수치에는 등급이 붙습니다. measured(도구 소요 시간처럼 Claude Code가 넘겨준 값), observed(모드가 이벤트 경계에서 직접 잰 값), reported(API가 보고한 토큰 사용량), inferred(나머지로 계산한 값)입니다. 작성자의 README는 Claude Code 2.1.287 이상을 요구합니다.

녹화에서는 작은 데모 프로젝트에서 이 모드를 불러온 Claude Code를 실행하고, Claude에게 README.md를 읽고 프로젝트를 한 문장으로 설명해 달라고 요청합니다. 턴이 진행되는 동안 하단 위의 상태 표시줄이 실시간으로 올라갑니다. 처음에는 model 92% · tools 0%, 이어서 model 100%와 진행 중인 요청 ▶ model claude-haiku-5-5, 그리고 경과 시간이 표시됩니다. 턴이 끝나면 /profile을 실행합니다. 보고서에는 모델 응답 대기 29.0초, 도구 5ms, 첫 토큰까지의 시간, 입력 토큰 82.3k, Read 호출 1회, 그리고 "모델을 기다린 시간이 에이전트 시간의 100%"라는 발견 사항이 나옵니다.

설치 블록의 어떤 방법을 써도 됩니다. 모두 작성자 본인의 마켓플레이스에서 바로 설치합니다. 이 마켓플레이스에는 여러 플러그인이 있으므로 agent-profiler를 고르세요. 상태 표시줄과 명령은 다음 세션을 시작할 때 나타납니다.

모듈 hooks/register.tsx는 메모리에 Profiler 객체를 두고 이벤트 경계에서 데이터를 넣어 줍니다. turn.start와 turn.complete, turn.step을 통한 모델 호출, tool.call을 통한 각 도구, 그리고 classic.PostToolUse로 전달되는 Claude Code 자체의 도구 소요 시간입니다. tool.call 훅은 관찰만 합니다. await next(e)로 도구가 끝나기를 기다리고 결과를 그대로 반환합니다. hooks/register.tsx에서:

on('tool.call', async ($, e, next) => {
  anonymous += 1
  const id = e.tool_use_id ?? `anonymous-${anonymous}`
  const tool = String(e.tool)
  safe(() => profiler.toolStart(Date.now(), { id, tool, agentId: e.agentId, input: summarizeInput(tool, e as unknown as Record<string, unknown>) }))
  paint($)
  try {
    const answer = await next(e)
    safe(() => profiler.toolEnd(Date.now(), id, toolOutcome(answer)))
    return answer
  } // ...
}).catch(($, e, next) => next(e))

기록의 모든 단계는 safe()를 거치므로 프로파일러 자체의 오류는 세션을 망가뜨리지 않고 버려집니다. 상태 표시줄은 초당 최대 두 번 다시 그려집니다. 각 턴이 끝나면 모드는 새로 끝난 스팬을 <outputDir>/<sessionId>/<loadId>-<seq>.otlp.json에 쓰고, 세션이 끝날 때 나머지와 세션 루트 스팬을 씁니다. 스팬 이름은 GenAI 규약(chat <model>, execute_tool <tool>, invoke_agent <type>)을 따릅니다. 스팬 ID와 트레이스 ID는 결정적이므로 같은 세션을 두 번 보내도 같은 스팬이 됩니다. 메모리에는 요청과 도구 호출을 최대 20,000개까지 두며, 넘으면 끝난 턴 중 가장 오래된 것부터 버립니다.

옵션 세 가지가 /plugin 설정 메뉴나 pluginConfigs에 있습니다.

Jaeger에서 트레이스를 보려면 저장소의 examples/jaeger/docker-compose.yml을 실행하고, otlpEndpoint를 http://localhost:4318로 설정한 뒤 http://localhost:16686을 엽니다. Grafana Tempo도 같은 OTLP/HTTP 엔드포인트를 받습니다.

실행하기 전에 플러그인이 실행할 수 있는 파일을 읽었습니다. .claude-plugin/plugin.json, hooks/hooks.json, 그리고 hooks/register.tsx와 Jaeger compose 파일은 전체를 읽었습니다. hooks/core/의 모듈 11개 중 export.ts, otlp.ts, redact.ts와 profiler.ts의 입력 요약 부분은 전체를 읽었고, 모든 모듈에서 네트워크, 프로세스, 파일, eval, import(), 환경 변수 호출을 검색했습니다(검색에 걸린 것은 register.tsx뿐입니다). 테스트 파일은 목록만 확인했고 읽지는 않았습니다. package.json, 설치 스크립트, 바이너리, 번들되거나 압축된 코드, eval, 동적 import()는 없습니다. hooks/ 소스에는 폭이 없는 문자나 숨은 문자가 없으며, ASCII가 아닌 문자는 █, ░, ·, ⏱ 같은 화면에 보이는 상태 및 보고서 기호뿐입니다. 이 모드는 프롬프트나 도구 결과에 텍스트를 주입하지 않습니다.

주목할 만한 발견 사항:

• 기본적으로 파일을 씁니다. 매 턴 이후와 세션 종료 시 $.fs.write를 호출해 outputDir을 설정하지 않으면 ~/.claude/agent-profiler/<sessionId>/에 씁니다. 플러그인 자신의 폴더이고 settings.json이나 셸 파일은 아니지만, 묻지 않고 기록됩니다. 파일에는 소요 시간, 토큰 수, 모델 이름, 도구 이름, Read/Edit/Write의 파일 경로, 각 Bash 명령의 범주(test, build 등)가 들어 있습니다. 파일 경로는 항상 내보내집니다. 프롬프트, Bash 명령, 검색 패턴은 exportCommandText를 켰을 때만 내보내집니다.
• 네트워크는 직접 선택했을 때만. $.http.fetch는 otlpEndpoint가 비어 있지 않을 때만 호출되며, 같은 트레이스 JSON을 <endpoint>/v1/traces로 POST할 뿐입니다. 호스트는 입력한 그대로입니다. 원격 수집기를 지정하면 파일 경로와, exportCommandText를 켰다면 가려진 명령이 내 컴퓨터 밖으로 나갑니다. README는 가리기가 최선을 다하는 수준이라고 경고합니다.
• 환경 변수 하나, HOME을 읽습니다. outputDir의 ~를 펼치기 위해서입니다.
• 도구 호출을 가로채지만 바꾸지는 않습니다. tool.call과 tool.check는 관찰만 하고 그대로 통과시키며, 둘 다 .catch 보호가 있습니다. 거부하거나 고쳐 쓰는 일은 없습니다. claude plugin validate는 classic.* 훅도 .catch 없는 게이팅 훅으로 나열하지만, 실제로는 next(e)를 반환하는 관찰용입니다. validate에 따르면 조직이 Claude Code를 관리하는 환경에서는 classic.* 훅이 실행되지 않으므로, 그곳에서는 보고서가 불완전할 수 있습니다.
• 프로세스, 데몬, 모델 호출이 없습니다. 명령을 실행하지 않고 백그라운드 서비스도 없습니다. 쓰는 것은 세션 안의 타이머뿐입니다.
• 선택적 외부 서비스. Jaeger나 Tempo는 트레이스를 볼 때만 필요합니다. compose 파일은 jaegertracing/all-in-one:latest를 가져오며, 모드가 직접 실행하지는 않습니다.
• 라이선스. Apache-2.0(저장소 루트의 LICENSE).

claude plugin validate는 오류와 경고 없이 위의 참고 사항만 보고했습니다. 작성자의 11개 파일, 67개 테스트는 Claude Code 2.1.303에서 claude plugin test로 모두 통과했습니다.

macOS의 Claude Code 2.1.303에서 validate, 작성자의 테스트, 데모 녹화를 확인했습니다. README에 따르면 작성자 본인의 엔드 투 엔드 검증은 2.1.280에서 이루어졌고, 이벤트 형태는 2.1.292 타입 선언을 따릅니다. 패널과 상태 표시줄은 터미널과 데스크톱 Code 탭에서 그려지지만 VS Code 채팅 패널과 claude -p에서는 그려지지 않습니다. /profile 텍스트는 어디서나 동작합니다.

• 상태 표시줄이나 명령이 없을 때. claude --version이 2.1.287 이상인지 확인하고, 실행 중인 세션에 설치했다면 /reload-plugins를 실행하세요.
• 트레이스 파일이 없을 때. 세션 ID를 알기 전에는 아무것도 쓰지 않습니다. 쓰기에 실패하면 토스트가 한 번 표시되므로 outputDir에 쓸 수 있는지 확인하세요.
• 핫 리로드 후 수치가 초기화될 때. 메모리의 상태는 처음부터 다시 시작하지만, 이미 쓰인 묶음은 이전 로드 ID 아래 디스크에 남습니다.
• Bash로 바뀐 파일. 반복 읽기 감지에는 보이지 않습니다.
• 모델 서버 내부의 시간(대기열, 프리필, 디코딩)은 어떤 클라이언트 쪽 도구로도 나눌 수 없습니다. 첫 토큰까지의 시간에 함께 들어 있습니다.